dynamic-cli 0.10.0

//! REPL (Read-Eval-Print Loop) implementation
//!
//! This module provides an interactive REPL interface with:
//! - Line editing (arrow keys, history navigation)
//! - Per-application command history (persistent across sessions)
//! - Tab completion of command names, `:` directives and option flags
//! - Colored prompts and error display
//! - `:`-prefixed directives (`:help`, `:load`, `:quit`, `:exit`), whose
//!   names can be overridden in the configuration
//!
//! # Example
//!
//! ```no_run
//! use dynamic_cli::interface::ReplInterface;
//! use dynamic_cli::prelude::*;
//!
//! # #[derive(Default)]
//! # struct MyContext;
//! # impl ExecutionContext for MyContext {
//! #     fn as_any(&self) -> &dyn std::any::Any { self }
//! #     fn as_any_mut(&mut self) -> &mut dyn std::any::Any { self }
//! # }
//! # fn main() -> dynamic_cli::Result<()> {
//! let registry = CommandRegistry::new();
//! let context = Box::new(MyContext::default());
//!
//! let repl = ReplInterface::new(registry, context, "myapp".to_string(), None, None)?;
//! repl.run()?;
//! # Ok(())
//! # }
//! ```

use std::path::PathBuf;
use std::sync::Arc;

use rustyline::completion::{Completer, Pair};
use rustyline::error::ReadlineError;
use rustyline::highlight::Highlighter;
use rustyline::hint::Hinter;
use rustyline::validate::Validator;
use rustyline::{CompletionType, Config, Context, Editor, Helper};

use crate::config::directive::{
    effective_directives, DirectiveDefinition, ReplDirective, DIRECTIVE_PREFIX,
};
use crate::config::schema::CommandsConfig;
use crate::context::ExecutionContext;
use crate::error::{display_error, DynamicCliError, ExecutionError, ParseError, Result};
use crate::help::{command_help_footer, DefaultHelpFormatter, HelpFormatter};
use crate::parser::{ParsedArgs, ReplParser};
use crate::registry::CommandRegistry;

// ============================================================================
// DcliCompleter
// ============================================================================

/// Tab-completion engine for the REPL.
///
/// Completes at three depth levels driven by the YAML configuration:
///
/// | Input                    | Candidates                                     |
/// |--------------------------|------------------------------------------------|
/// | `<Tab>`                  | all command names + aliases                    |
/// | `he<Tab>`                | command names/aliases starting with `he`       |
/// | `:<Tab>`                 | all directive names + aliases, with their `:`  |
/// | `:he<Tab>`               | directive names/aliases starting with `he`     |
/// | `hello <Tab>`            | long and short option flags of `hello`         |
/// | `hello --<Tab>`          | long flags of `hello`                          |
/// | `hello -<Tab>`           | short flags of `hello`                         |
///
/// Directives are completed under their effective names, so a renamed or
/// translated directive completes under its configured name. Positional
/// argument values, including the argument of a directive, are not
/// completed.
///
/// The completer holds `Arc` references so it shares the same data as
/// `ReplInterface` without duplication or unsafe aliasing.
struct DcliCompleter {
    /// Shared registry — single source of truth for command names and aliases.
    registry: Arc<CommandRegistry>,

    /// Shared configuration — source of truth for option flags.
    /// `None` when the REPL was constructed without a config.
    config: Option<Arc<CommandsConfig>>,

    /// Shared effective directive table — source of truth for directive
    /// names and aliases.
    directives: Arc<[DirectiveDefinition]>,
}

impl DcliCompleter {
    fn new(
        registry: Arc<CommandRegistry>,
        config: Option<Arc<CommandsConfig>>,
        directives: Arc<[DirectiveDefinition]>,
    ) -> Self {
        Self {
            registry,
            config,
            directives,
        }
    }

    /// Directive names and aliases starting with `typed`, each with its
    /// leading `:`. `typed` includes the `:`.
    fn directives_matching(&self, typed: &str) -> Vec<String> {
        self.directives
            .iter()
            .flat_map(|def| std::iter::once(&def.name).chain(&def.aliases))
            .map(|name| format!("{}{}", DIRECTIVE_PREFIX, name))
            .filter(|candidate| candidate.starts_with(typed))
            .collect()
    }

    /// Collect all flag completions for a given canonical command name.
    ///
    /// Returns both long forms (`--flag`) and short forms (`-f`) for every
    /// option defined on the command.
    fn flags_for(&self, command_name: &str) -> Vec<String> {
        let config = match &self.config {
            Some(c) => c,
            None => return vec![],
        };

        let cmd_def = match config.commands.iter().find(|c| c.name == command_name) {
            Some(d) => d,
            None => return vec![],
        };

        let mut flags = Vec::new();
        for opt in &cmd_def.options {
            if let Some(long) = &opt.long {
                flags.push(format!("--{}", long));
            }
            if let Some(short) = &opt.short {
                flags.push(format!("-{}", short));
            }
        }
        flags
    }
}

impl Completer for DcliCompleter {
    type Candidate = Pair;

    fn complete(
        &self,
        line: &str,
        pos: usize,
        _ctx: &Context<'_>,
    ) -> rustyline::Result<(usize, Vec<Pair>)> {
        // Work only on the portion of the line up to the cursor.
        let line = &line[..pos];
        let tokens: Vec<&str> = line.split_whitespace().collect();

        // ── Level 1: no token yet, or first token still being typed ──────────
        // Complete command names and aliases.
        let completing_first_token =
            tokens.is_empty() || (tokens.len() == 1 && !line.ends_with(' '));

        if completing_first_token {
            let prefix = tokens.first().copied().unwrap_or("");
            let start = pos - prefix.len();

            // Command names cannot start with `:` (rejected by the config
            // validator), so a `:` prefix selects directives only.
            let names: Vec<String> = if prefix.starts_with(DIRECTIVE_PREFIX) {
                self.directives_matching(prefix)
            } else {
                self.registry
                    .list_commands()
                    .into_iter()
                    .flat_map(|def| {
                        let mut names = vec![def.name.clone()];
                        names.extend(def.aliases.clone());
                        names
                    })
                    .filter(|name| name.starts_with(prefix))
                    .collect()
            };

            let mut candidates: Vec<Pair> = names
                .into_iter()
                .map(|name| Pair {
                    display: name.clone(),
                    replacement: name,
                })
                .collect();

            candidates.sort_by(|a, b| a.display.cmp(&b.display));
            return Ok((start, candidates));
        }

        // ── Level 2: first token is a complete command, completing flags ──────
        // Resolve the command name (handles aliases).
        let command_token = tokens[0];
        let canonical = match self.registry.resolve_name(command_token) {
            Some(name) => name.to_string(),
            None => return Ok((pos, vec![])),
        };

        // The word being completed (may be empty if cursor follows a space).
        let current_word = if line.ends_with(' ') {
            ""
        } else {
            tokens.last().copied().unwrap_or("")
        };

        // Only offer flag completions when the current word looks like a flag
        // or when the user pressed Tab on an empty position after the command.
        let is_flag_context = current_word.is_empty() || current_word.starts_with('-');

        if !is_flag_context {
            return Ok((pos, vec![]));
        }

        let start = pos - current_word.len();
        let mut candidates: Vec<Pair> = self
            .flags_for(&canonical)
            .into_iter()
            .filter(|flag| flag.starts_with(current_word))
            .map(|flag| Pair {
                display: flag.clone(),
                replacement: flag,
            })
            .collect();

        candidates.sort_by(|a, b| a.display.cmp(&b.display));
        Ok((start, candidates))
    }
}

// ============================================================================
// DcliHelper — rustyline Helper glue
// ============================================================================

/// Rustyline `Helper` implementation that wires `DcliCompleter` into the
/// editor. The remaining traits (`Hinter`, `Highlighter`, `Validator`) use
/// their no-op default implementations.
struct DcliHelper {
    completer: DcliCompleter,
}

impl DcliHelper {
    fn new(
        registry: Arc<CommandRegistry>,
        config: Option<Arc<CommandsConfig>>,
        directives: Arc<[DirectiveDefinition]>,
    ) -> Self {
        Self {
            completer: DcliCompleter::new(registry, config, directives),
        }
    }
}

impl Helper for DcliHelper {}

impl Completer for DcliHelper {
    type Candidate = Pair;

    fn complete(
        &self,
        line: &str,
        pos: usize,
        ctx: &Context<'_>,
    ) -> rustyline::Result<(usize, Vec<Pair>)> {
        self.completer.complete(line, pos, ctx)
    }
}

// No-op implementations required by the Helper supertrait bound.
impl Hinter for DcliHelper {
    type Hint = String;
}

impl Highlighter for DcliHelper {}

impl Validator for DcliHelper {}

// ============================================================================
// ReplInterface
// ============================================================================

/// REPL (Read-Eval-Print Loop) interface
///
/// Provides an interactive command-line interface with:
/// - Line editing and history
/// - Per-application persistent command history
/// - Tab completion (commands, aliases, directives, option flags)
/// - Graceful error handling
/// - `:`-prefixed directives and `--help` interception
///
/// # Architecture
///
/// ```text
/// User input → rustyline (DcliHelper) → ReplParser → CommandExecutor → Handler
///                    ↓                                      ↓
///             Tab completion                         ExecutionContext
///    (commands, directives, flags)
/// ```
///
/// # Directives
///
/// A line starting with `:` is a framework directive; any other line is an
/// application command, so a directive never shadows a command. With the
/// default names:
///
/// | Directive         | Aliases    | Effect                                        |
/// |-------------------|------------|-----------------------------------------------|
/// | `:help [command]` | `:h`, `:?` | Application help, or the help of one command  |
/// | `:load <path>`    |            | Run every line of a script file               |
/// | `:quit`           | `:q`       | Save the session history, then leave          |
/// | `:exit`           |            | Leave without saving the session history      |
///
/// Names, aliases and descriptions come from the configuration's
/// `directives:` section when present (see [`crate::config::directive`]);
/// a renamed directive no longer answers to its default name. `exit` or
/// `quit` typed without `:` is an ordinary command; when the application
/// has no such command, the error suggests the matching directive.
///
/// `--help`, `-h`, `--help <command>` and `<command> --help` are also
/// intercepted and rendered like `:help`.
///
/// # History
///
/// Command history is stored per application under the XDG data directory:
/// - Linux/macOS: `~/.local/share/<app_name>/history`
/// - Windows:     `%LOCALAPPDATA%\<app_name>\history`
///
/// The history file is read when the REPL starts. During the session, new
/// entries are kept in memory; the file is written only when the session
/// ends with `:quit` or end of input (Ctrl-D). Leaving with `:exit`, an
/// input error, a handler that exits the process, a panic or a signal
/// leaves the file as it was at startup.
///
/// Lines containing a `secure: true` argument are never added to history.
/// Lines that fail to parse and directive lines are not added either.
pub struct ReplInterface {
    /// Shared command registry — single source of truth for names, aliases,
    /// definitions, and handlers.
    registry: Arc<CommandRegistry>,

    /// Execution context passed to every command handler.
    context: Box<dyn ExecutionContext>,

    /// Fully rendered prompt string (e.g., "myapp > "), built at construction
    /// time from the `prompt` argument and `prompt_suffix` below.
    prompt: String,

    /// Suffix appended after the app-name segment to build both `prompt`
    /// and the default multi-line continuation prompt (#67).
    ///
    /// Sourced from `config.metadata.prompt_suffix` when a config is
    /// supplied, falling back to [`crate::config::schema::default_prompt_suffix`] otherwise —
    /// stored separately (rather than re-parsed out of `prompt`) so the
    /// multi-line default stays correct regardless of what the configured
    /// suffix actually is.
    prompt_suffix: String,

    /// Rustyline editor with tab-completion support.
    editor: Editor<DcliHelper, rustyline::history::DefaultHistory>,

    /// History file path.
    history_path: Option<PathBuf>,

    /// Application configuration — shared with the completer and used by the
    /// help formatter. `None` when no config was supplied at construction.
    config: Option<Arc<CommandsConfig>>,

    /// Help formatter — renders `--help` output.
    /// `None` when the application was built without a formatter.
    help_formatter: Option<Box<dyn HelpFormatter>>,

    /// Base (app-name-equivalent) segment of the continuation prompt shown
    /// while a `\`-continued command is being accumulated (#67).
    ///
    /// `None` (the default) means the base falls back to `"..."`. Either
    /// way, `prompt_suffix` is always appended — this field overrides only
    /// the segment that replaces the app name, exactly like `prompt`
    /// (the constructor argument) only ever supplied the app-name segment
    /// of the main prompt.
    prompt_multiline: Option<String>,

    /// Effective directive table: the configured overrides merged with the
    /// defaults, one entry per [`ReplDirective`] in `ReplDirective::ALL`
    /// order. Defaults only when no config was supplied. Shared with the
    /// completer.
    directives: Arc<[DirectiveDefinition]>,
}

/// What the REPL session does after a line
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum SessionControl {
    /// Read the next line
    Continue,
    /// Leave the REPL, writing the session history first or not
    Leave { save_history: bool },
}

impl ReplInterface {
    /// Create a new REPL interface.
    ///
    /// All configuration is supplied at construction time so that the
    /// tab-completion engine and the help formatter share the same data
    /// without duplication.
    ///
    /// # Arguments
    ///
    /// * `registry`       — Command registry with all registered commands.
    /// * `context`        — Execution context passed to handlers.
    /// * `prompt`         — Prompt prefix (e.g., `"myapp"`). The displayed
    ///   prompt is `prompt` followed by `config.metadata.prompt_suffix`
    ///   (e.g., `"myapp > "`) when `config` is supplied, or by
    ///   `default_prompt_suffix()` (`"myapp > "`) otherwise — the suffix is
    ///   never hardcoded independently of the config.
    /// * `config`         — Application configuration for completion, help,
    ///   and the prompt suffix. Pass `None` to disable all three.
    /// * `help_formatter` — Help formatter implementation.
    ///   Pass `None` to use [`DefaultHelpFormatter`] lazily,
    ///   or supply a custom implementation.
    ///
    /// # Errors
    ///
    /// Returns an error if rustyline initialisation fails (rare).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use dynamic_cli::interface::ReplInterface;
    /// use dynamic_cli::prelude::*;
    ///
    /// # #[derive(Default)]
    /// # struct MyContext;
    /// # impl ExecutionContext for MyContext {
    /// #     fn as_any(&self) -> &dyn std::any::Any { self }
    /// #     fn as_any_mut(&mut self) -> &mut dyn std::any::Any { self }
    /// # }
    /// # fn main() -> dynamic_cli::Result<()> {
    /// let registry = CommandRegistry::new();
    /// let context = Box::new(MyContext::default());
    ///
    /// // Without completion or help:
    /// let repl = ReplInterface::new(registry, context, "myapp".to_string(), None, None)?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn new(
        registry: CommandRegistry,
        context: Box<dyn ExecutionContext>,
        prompt: String,
        config: Option<CommandsConfig>,
        help_formatter: Option<Box<dyn HelpFormatter>>,
    ) -> Result<Self> {
        // Wrap registry in Arc — shared with the completer.
        let registry = Arc::new(registry);

        // Determine the prompt suffix *before* config is moved into the Arc
        // below — sourced from the live config when present (config-first,
        // principle 7), falling back to the same default the schema itself
        // uses when no config was supplied.
        let prompt_suffix = config
            .as_ref()
            .map(|c| c.metadata.prompt_suffix.clone())
            .unwrap_or_else(crate::config::schema::default_prompt_suffix);

        // DA-030 (#92): the directive table is fixed for the session.
        let directives: Arc<[DirectiveDefinition]> = effective_directives(
            config
                .as_ref()
                .map(|c| c.directives.as_slice())
                .unwrap_or_default(),
        )
        .into();

        // Wrap config in Arc if present — shared with the completer.
        let config: Option<Arc<CommandsConfig>> = config.map(Arc::new);

        // Build the rustyline editor with Tab completion enabled.
        let rl_config = Config::builder()
            .completion_type(CompletionType::List)
            .build();

        let helper = DcliHelper::new(
            Arc::clone(&registry),
            config.clone(),
            Arc::clone(&directives),
        );

        let mut editor = Editor::with_config(rl_config).map_err(|e| {
            ExecutionError::CommandFailed(anyhow::anyhow!("Failed to initialize REPL: {}", e))
        })?;
        editor.set_helper(Some(helper));

        // Determine history file path using the prompt as the app name.
        let history_path = Self::get_history_path(&prompt);

        let mut repl = Self {
            registry,
            context,
            prompt: format!("{}{}", prompt, prompt_suffix),
            prompt_suffix,
            editor,
            history_path,
            config,
            help_formatter,
            prompt_multiline: None,
            directives,
        };

        repl.load_history();

        Ok(repl)
    }

    /// Override the base segment of the continuation prompt shown while a
    /// `\`-continued command is being accumulated (#67).
    ///
    /// `prompt` here plays the same role as the app-name segment passed to
    /// [`ReplInterface::new`] for the main prompt: only the base is
    /// supplied, `prompt_suffix` (from the config, or the default) is
    /// always appended after it by `effective_prompt_multiline()`.
    /// When this setter is never called, the base defaults to `"..."`.
    ///
    /// Purely additive — consuming `self` and returning `Self` like every
    /// other fluent setter in this crate; no existing `ReplInterface::new()`
    /// call site changes.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use dynamic_cli::interface::ReplInterface;
    /// use dynamic_cli::prelude::*;
    ///
    /// # #[derive(Default)]
    /// # struct MyContext;
    /// # impl ExecutionContext for MyContext {
    /// #     fn as_any(&self) -> &dyn std::any::Any { self }
    /// #     fn as_any_mut(&mut self) -> &mut dyn std::any::Any { self }
    /// # }
    /// # fn main() -> dynamic_cli::Result<()> {
    /// let registry = CommandRegistry::new();
    /// let context = Box::new(MyContext::default());
    ///
    /// let repl = ReplInterface::new(registry, context, "rpn".to_string(), None, None)?
    ///     .with_prompt_multiline("_ _ _".to_string());
    /// # Ok(())
    /// # }
    /// ```
    pub fn with_prompt_multiline(mut self, prompt: String) -> Self {
        self.prompt_multiline = Some(prompt);
        self
    }

    /// The prompt actually displayed while accumulating a `\`-continued
    /// command (#67).
    ///
    /// With an override set via
    /// [`with_prompt_multiline`][Self::with_prompt_multiline], the base is
    /// used as-is, followed by `prompt_suffix` unchanged (e.g. base
    /// `"_ _ _"` + suffix `" $ "` → `"_ _ _ $ "`).
    ///
    /// Without an override, the default base `"..."` is followed by
    /// `prompt_suffix` **with its leading whitespace stripped**, so that
    /// `"rpn > "` becomes `"...> "`: `"..."` takes the place of the app
    /// name *and* of the space right after it, rather than of the app name
    /// alone, so it reads as one continuous mark
    /// against the separator glyph instead of leaving a stray gap
    /// (`"... > "`). This asymmetry is deliberate — an explicit override is
    /// the caller's own spacing choice and is never second-guessed.
    fn effective_prompt_multiline(&self) -> String {
        match &self.prompt_multiline {
            Some(base) => format!("{}{}", base, self.prompt_suffix),
            None => format!("...{}", self.prompt_suffix.trim_start()),
        }
    }

    /// Render the application help, or the help of `command`.
    ///
    /// The application help is followed by the directive list, then by the
    /// line on the help directive (`Type ':help <command>' …`); both use
    /// the effective directive names.
    ///
    /// Uses the formatter supplied to [`ReplInterface::new`], or
    /// [`DefaultHelpFormatter`] when none was supplied. Returns `None`
    /// without a configuration, since there is nothing to render.
    fn render_help(&self, command: Option<&str>) -> Option<String> {
        let config = self.config.as_deref()?;
        // `DefaultHelpFormatter` is a unit struct: the fallback costs no
        // allocation and is only built when help is actually requested.
        let default_formatter = DefaultHelpFormatter::new();
        let formatter: &dyn HelpFormatter =
            self.help_formatter.as_deref().unwrap_or(&default_formatter);

        Some(match command {
            Some(cmd) => formatter.format_command(config, cmd),
            None => {
                let mut out = formatter.format_app(config);
                out.push_str(&formatter.format_directives(&self.directives));
                out.push_str(&command_help_footer(
                    "Type",
                    &format!(
                        "{}{} <command>",
                        DIRECTIVE_PREFIX,
                        self.help_directive_name()
                    ),
                ));
                out
            }
        })
    }

    /// Try to handle a `--help` / `-h` request.
    ///
    /// Returns `Some(output)` when the line is a help request and a
    /// configuration is available, `None` otherwise (normal command
    /// processing continues). Rendering goes through
    /// [`render_help`][Self::render_help].
    ///
    /// Recognized patterns (case-sensitive):
    ///
    /// | Input              | Output                    |
    /// |--------------------|---------------------------|
    /// | `--help`           | Application-level help    |
    /// | `-h`               | Application-level help    |
    /// | `--help <command>` | Per-command help          |
    /// | `-h <command>`     | Per-command help          |
    /// | `<command> --help` | Per-command help          |
    /// | `<command> -h`     | Per-command help          |
    fn try_handle_help(&self, line: &str) -> Option<String> {
        let trimmed = line.trim();

        if trimmed == "--help" || trimmed == "-h" {
            return self.render_help(None);
        }

        if let Some(rest) = trimmed
            .strip_prefix("--help ")
            .or_else(|| trimmed.strip_prefix("-h "))
        {
            let cmd = rest.trim();
            if !cmd.is_empty() {
                return self.render_help(Some(cmd));
            }
        }

        let parts: Vec<&str> = trimmed.split_whitespace().collect();
        if parts.len() >= 2 {
            let last = *parts.last().unwrap();
            if last == "--help" || last == "-h" {
                return self.render_help(Some(parts[0]));
            }
        }

        None
    }

    /// Dispatch one input line: a directive when it starts with `:`, an
    /// application command otherwise.
    ///
    /// Shared by [`run`][Self::run] and [`load_script`][Self::load_script].
    /// Returns what the session does next; only `:quit` and `:exit` ask to
    /// leave. Leaving, and writing the history, is up to the caller.
    fn handle_line(&mut self, line: &str) -> Result<SessionControl> {
        let line = line.trim();

        if line.starts_with(DIRECTIVE_PREFIX) {
            return self.dispatch_directive(line);
        }

        self.execute_line(line)?;
        Ok(SessionControl::Continue)
    }

    /// Directive whose effective name or alias is `name` (typed without
    /// its `:`), if any.
    fn resolve_directive(&self, name: &str) -> Option<ReplDirective> {
        self.directives
            .iter()
            .find(|def| def.name == name || def.aliases.iter().any(|alias| alias == name))
            .map(|def| def.implementation)
    }

    /// Effective definition of `directive`.
    fn directive_definition(&self, directive: ReplDirective) -> &DirectiveDefinition {
        self.directives
            .iter()
            .find(|def| def.implementation == directive)
            // The table holds every variant: built by `effective_directives`.
            .expect("directive table covers every ReplDirective")
    }

    /// Run one directive line (starting with `:`).
    ///
    /// The first word after `:` selects the directive through the effective
    /// table; the rest of the line is its argument.
    fn dispatch_directive(&mut self, line: &str) -> Result<SessionControl> {
        let body = &line[DIRECTIVE_PREFIX.len_utf8()..];
        let (name, rest) = match body.split_once(char::is_whitespace) {
            Some((name, rest)) => (name, rest.trim()),
            None => (body, ""),
        };

        let directive = self
            .resolve_directive(name)
            .ok_or_else(|| self.unknown_directive_error(name))?;

        // DA-030 (#92): exhaustive match — a new variant must be handled here.
        match directive {
            ReplDirective::Help => {
                if rest.split_whitespace().count() > 1 {
                    return Err(self.usage_error(name, directive, "takes at most one command"));
                }
                let command = (!rest.is_empty()).then_some(rest);
                let output = self.render_help(command).ok_or_else(|| {
                    DynamicCliError::Execution(ExecutionError::CommandFailed(anyhow::anyhow!(
                        "help is not available"
                    )))
                })?;
                print!("{}", output);
                Ok(SessionControl::Continue)
            }
            ReplDirective::Load => {
                if rest.is_empty() {
                    return Err(self.usage_error(name, directive, "requires a file path"));
                }
                self.load_script(rest)?;
                Ok(SessionControl::Continue)
            }
            ReplDirective::Quit | ReplDirective::Exit => {
                if !rest.is_empty() {
                    return Err(self.usage_error(name, directive, "takes no argument"));
                }
                Ok(SessionControl::Leave {
                    save_history: directive == ReplDirective::Quit,
                })
            }
        }
    }

    /// Error for a directive typed as `:<typed>` with invalid arguments.
    fn usage_error(&self, typed: &str, directive: ReplDirective, problem: &str) -> DynamicCliError {
        DynamicCliError::Parse(ParseError::InvalidSyntax {
            details: format!("`{}{}` {}", DIRECTIVE_PREFIX, typed, problem),
            hint: Some(format!(
                "Usage: {}",
                self.directive_definition(directive).usage_line()
            )),
        })
    }

    /// Error for `:<typed>` matching no directive, listing the effective
    /// directive names.
    fn unknown_directive_error(&self, typed: &str) -> DynamicCliError {
        let available: Vec<String> = self
            .directives
            .iter()
            .map(|def| format!("{}{}", DIRECTIVE_PREFIX, def.name))
            .collect();
        DynamicCliError::Parse(ParseError::InvalidSyntax {
            details: format!("Unknown directive '{}{}'", DIRECTIVE_PREFIX, typed),
            hint: Some(format!("Available directives: {}", available.join(", "))),
        })
    }

    /// Complete an unknown-command error for the REPL.
    ///
    /// - When the unknown command is a directive name or alias typed
    ///   without its `:` (`quit`), the directive (`:quit`) becomes the
    ///   first suggestion. The parser only reports an unknown command when
    ///   the application has no command of that name, so a command always
    ///   takes precedence.
    /// - The hint names the help directive under its effective name:
    ///   `Type ':help' for available commands`.
    ///
    /// Any other error is returned unchanged.
    fn complete_unknown_command(&self, error: DynamicCliError) -> DynamicCliError {
        match error {
            DynamicCliError::Parse(ParseError::UnknownCommand {
                command,
                mut suggestions,
                ..
            }) => {
                if self.resolve_directive(&command).is_some() {
                    let directive = format!("{}{}", DIRECTIVE_PREFIX, command);
                    suggestions.retain(|s| *s != directive);
                    suggestions.insert(0, directive);
                }
                DynamicCliError::Parse(ParseError::UnknownCommand {
                    command,
                    suggestions,
                    hint: Some(format!(
                        "Type '{}{}' for available commands",
                        DIRECTIVE_PREFIX,
                        self.help_directive_name()
                    )),
                })
            }
            other => other,
        }
    }

    /// Effective name of the help directive (`help` unless overridden).
    fn help_directive_name(&self) -> &str {
        &self.directive_definition(ReplDirective::Help).name
    }

    /// Run every line of the script at `path` (`:load <path>`).
    ///
    /// Each non-blank, non-comment (`#`-prefixed) line goes through
    /// [`handle_line`][Self::handle_line], like a typed line: commands,
    /// `--help` and the `:help` / `:load` directives run normally. A
    /// directive that leaves the session (`:quit`, `:exit`, under any of
    /// their names) is refused: it is reported and skipped, and the script
    /// goes on.
    ///
    /// There is no error-policy parameter, unlike
    /// [`CliInterface::run_script`][crate::interface::CliInterface::run_script]:
    /// a failing line is reported inline (via [`display_error`]) and the
    /// load always continues, then prints a `succeeded/attempted` summary.
    ///
    /// Loaded lines follow the REPL's scalar-only parsing path, not
    /// `run_script()`'s typed/repeatable-options path, and are not added to
    /// history. A script that loads itself (directly or through another
    /// file) recurses until the file handle limit or the stack is
    /// exhausted: no cycle detection is implemented.
    fn load_script(&mut self, path: &str) -> Result<()> {
        let content = std::fs::read_to_string(path).map_err(|e| {
            DynamicCliError::Execution(ExecutionError::CommandFailed(anyhow::anyhow!(
                "failed to read script file {}: {}",
                path,
                e
            )))
        })?;

        let mut attempted = 0usize;
        let mut succeeded = 0usize;

        for (idx, raw_line) in content.lines().enumerate() {
            let line_number = idx + 1;
            let script_line = raw_line.trim();

            if script_line.is_empty() || script_line.starts_with('#') {
                continue;
            }

            attempted += 1;

            match self.handle_line(script_line) {
                Ok(SessionControl::Continue) => succeeded += 1,
                Ok(SessionControl::Leave { .. }) => {
                    // Nothing has happened yet: leaving is done by `run()`.
                    let typed = script_line.split_whitespace().next().unwrap_or_default();
                    eprintln!(
                        "  :load {} — line {}: '{}' cannot be used in a script; line skipped",
                        path, line_number, typed
                    );
                }
                Err(e) => {
                    eprintln!("  :load {} — line {}:", path, line_number);
                    display_error(&e);
                }
            }
        }

        println!(":load {path}: {succeeded}/{attempted} line(s) succeeded");
        Ok(())
    }

    /// Check whether a parsed command involves at least one secure argument.
    ///
    /// Looks up the command definition in `self.config` (if available) and
    /// returns `true` when any argument name present in `parsed_args` is
    /// marked `secure: true` in the YAML schema.
    fn has_secure_arg(
        &self,
        command_name: &str,
        parsed_args: &std::collections::HashMap<String, String>,
    ) -> bool {
        let config = match &self.config {
            Some(c) => c,
            None => return false,
        };

        let cmd_def = match config.commands.iter().find(|c| c.name == command_name) {
            Some(d) => d,
            None => return false,
        };

        cmd_def
            .arguments
            .iter()
            .any(|arg| arg.secure && parsed_args.contains_key(&arg.name))
    }

    /// Get the history file path for this application.
    ///
    /// Each application gets its own isolated history file under the
    /// XDG data directory:
    ///
    /// - Linux/macOS: `~/.local/share/<app_name>/history`
    /// - Windows:     `%LOCALAPPDATA%\<app_name>\history`
    fn get_history_path(app_name: &str) -> Option<PathBuf> {
        dirs::data_local_dir().map(|data_dir| data_dir.join(app_name).join("history"))
    }

    /// Load command history from file.
    fn load_history(&mut self) {
        if let Some(ref path) = self.history_path {
            if let Some(parent) = path.parent() {
                let _ = std::fs::create_dir_all(parent);
            }
            let _ = self.editor.load_history(path);
        }
    }

    /// Write the session history to the history file.
    ///
    /// Called only when the session ends with `:quit` or end of input.
    fn save_history(&mut self) {
        if let Some(ref path) = self.history_path {
            if let Err(e) = self.editor.save_history(path) {
                eprintln!("Warning: Failed to save command history: {}", e);
            }
        }
    }

    /// Run the REPL loop.
    ///
    /// Enters an interactive loop that:
    /// 1. Displays the prompt (or the continuation prompt while
    ///    accumulating a `\`-continued command, #69)
    /// 2. Reads user input (with tab completion)
    /// 3. Parses and executes the command
    /// 4. Displays results or errors
    /// 5. Repeats until `:quit`, `:exit` or end of input
    ///
    /// # Multi-line option accumulation (#69)
    ///
    /// A line ending in a trailing `\` is not dispatched: the marker is
    /// stripped and the fragment is buffered, the prompt switches to
    /// `effective_prompt_multiline()`,
    /// and another line is read. The first line that does *not* end in `\`
    /// completes the buffer — every fragment plus this final one are
    /// joined with a single space and dispatched exactly once, with the
    /// normal prompt restored. Only this fully reconstructed line (no `\`
    /// markers) can ever reach REPL history — the dispatch never sees a raw
    /// partial fragment.
    ///
    /// A `Ctrl+C` while accumulating discards the buffer and returns to
    /// the normal prompt, mirroring the familiar shell convention of
    /// abandoning a continued line on interrupt.
    ///
    /// This mechanism is entirely local to this loop: `execute_line()`,
    /// [`ReplParser`], and `CliParser` are untouched, and non-interactive
    /// paths (`run_script()`, `:load`) never go through it: without a live
    /// operator, nothing can answer a continuation prompt, so an incomplete
    /// command there fails instead of waiting for more input.
    ///
    /// # Returns
    ///
    /// - `Ok(())` when the session ends: `:quit` or end of input (Ctrl-D),
    ///   which save the session history, `:exit`, which does not, or an
    ///   input error, reported on stderr, which does not either
    /// - `Err(_)` is reserved for critical errors; command and directive
    ///   errors are displayed and the loop goes on
    ///
    /// # Example
    ///
    /// ```no_run
    /// use dynamic_cli::interface::ReplInterface;
    /// use dynamic_cli::prelude::*;
    ///
    /// # #[derive(Default)]
    /// # struct MyContext;
    /// # impl ExecutionContext for MyContext {
    /// #     fn as_any(&self) -> &dyn std::any::Any { self }
    /// #     fn as_any_mut(&mut self) -> &mut dyn std::any::Any { self }
    /// # }
    /// # fn main() -> dynamic_cli::Result<()> {
    /// let registry = CommandRegistry::new();
    /// let context = Box::new(MyContext::default());
    ///
    /// let repl = ReplInterface::new(registry, context, "myapp".to_string(), None, None)?;
    /// repl.run()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn run(mut self) -> Result<()> {
        let mut continuation_buffer: Vec<String> = Vec::new();

        loop {
            let prompt = if continuation_buffer.is_empty() {
                self.prompt.clone()
            } else {
                self.effective_prompt_multiline()
            };

            let readline = self.editor.readline(&prompt);

            match readline {
                Ok(raw_line) => {
                    let line = match Self::accumulate_line(&mut continuation_buffer, &raw_line) {
                        Some(line) => line,
                        // Still accumulating: read another line under the
                        // continuation prompt instead of dispatching.
                        None => continue,
                    };

                    if line.is_empty() {
                        continue;
                    }

                    // History entries are added inside execute_line(), after
                    // successful parsing and only when no secure argument is
                    // present; directives are never added.
                    match self.handle_line(&line) {
                        Ok(SessionControl::Continue) => {}
                        Ok(SessionControl::Leave { save_history }) => {
                            self.end_session(save_history);
                            break;
                        }
                        Err(e) => {
                            display_error(&e);
                        }
                    }
                }

                Err(ReadlineError::Interrupted) => {
                    println!("^C");
                    // A continued command doesn't survive an interrupt —
                    // same as a shell discarding a `\`-continued line.
                    continuation_buffer.clear();
                    continue;
                }

                // End of input (Ctrl-D) ends the session like `:quit`.
                Err(ReadlineError::Eof) => {
                    println!();
                    self.end_session(true);
                    break;
                }

                // DA-030 (#92): any other termination leaves the history
                // file untouched.
                Err(err) => {
                    eprintln!("Error reading input: {}", err);
                    break;
                }
            }
        }

        Ok(())
    }

    /// End the session: write the history when `save_history` is set, then
    /// say goodbye.
    fn end_session(&mut self, save_history: bool) {
        if save_history {
            self.save_history();
        }
        println!("Goodbye!");
    }

    /// Feed one raw input line into the `\`-continuation buffer (#69).
    ///
    /// Pure and I/O-free by design: [`run`][Self::run] is the only caller,
    /// but keeping this separate from the `rustyline`-driven loop makes the
    /// accumulation semantics themselves unit-testable without an
    /// interactive terminal.
    ///
    /// # Returns
    ///
    /// - `None` — `raw_line` ended in `\`; the marker was stripped and the
    ///   fragment pushed onto `buffer`. The caller should read another line
    ///   under the continuation prompt.
    /// - `Some(line)` — `raw_line` did not end in `\`, completing the
    ///   buffer. `buffer` is drained and every fragment (in order) plus
    ///   `raw_line` are joined with a single space; this is the
    ///   reconstructed line the caller should dispatch. When `buffer` was
    ///   already empty, `line` is simply `raw_line.trim()` — the ordinary,
    ///   non-continued case.
    fn accumulate_line(buffer: &mut Vec<String>, raw_line: &str) -> Option<String> {
        let trimmed = raw_line.trim();

        if let Some(fragment) = trimmed.strip_suffix('\\') {
            buffer.push(fragment.trim_end().to_string());
            return None;
        }

        if buffer.is_empty() {
            return Some(trimmed.to_string());
        }

        buffer.push(trimmed.to_string());
        Some(std::mem::take(buffer).join(" "))
    }

    /// Execute a single line of input.
    ///
    /// Parses the line and executes the corresponding command.
    /// `--help` and `-h` requests are intercepted before dispatch.
    /// Directives are handled earlier, by [`handle_line`][Self::handle_line].
    ///
    /// History is written here — after successful parsing — so that:
    /// - Failed or invalid commands are never persisted.
    /// - Lines containing a `secure: true` argument are silently omitted.
    fn execute_line(&mut self, line: &str) -> Result<()> {
        if let Some(output) = self.try_handle_help(line) {
            print!("{}", output);
            return Ok(());
        }

        let parser = ReplParser::new(&self.registry);
        let parsed = parser
            .parse_line(line)
            .map_err(|e| self.complete_unknown_command(e))?;

        // Write to history only on successful parse and when no secure
        // argument is present in the parsed command.
        if !self.has_secure_arg(&parsed.command_name, &parsed.arguments) {
            let _ = self.editor.add_history_entry(line);
        }

        // Sync tried first (unchanged behaviour), then async via `block_on`
        // per DA-022 (#8). Safe here because the REPL loop is strictly sequential
        // — one command finishes (readline blocks regardless) before the
        // next line is even read, so there is no other async task waiting
        // that `block_on` could starve.
        //
        // Wrapped via `from_scalars`: `ReplParser::parse_line` still
        // produces a plain `HashMap<String, String>`: repeatable options
        // have no interactive REPL-typing use case, see DD-024 (#21). Every
        // handler receives `&ParsedArgs`
        // regardless of dispatch path (#39); the REPL path just never
        // populates `ParsedValue::Repeated` entries.
        let parsed_args = ParsedArgs::from_scalars(parsed.arguments);
        if let Some(handler) = self.registry.get_handler_sync(&parsed.command_name) {
            handler.execute(&mut *self.context, &parsed_args)?;
        } else if let Some(handler) = self.registry.get_handler_async(&parsed.command_name) {
            futures::executor::block_on(handler.execute(&mut *self.context, &parsed_args))?;
        } else {
            return Err(DynamicCliError::Execution(
                ExecutionError::handler_not_found(&parsed.command_name, "unknown"),
            ));
        }

        Ok(())
    }
}

// ============================================================================
// Tests
// ============================================================================

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::schema::{
        ArgumentDefinition, ArgumentType, CommandDefinition, OptionDefinition,
    };
    use rustyline::history::History;
    use std::collections::HashMap;

    #[derive(Default)]
    struct TestContext {
        executed_commands: Vec<String>,
    }

    impl ExecutionContext for TestContext {
        fn as_any(&self) -> &dyn std::any::Any {
            self
        }
        fn as_any_mut(&mut self) -> &mut dyn std::any::Any {
            self
        }
    }

    struct TestHandler {
        name: String,
    }

    impl crate::executor::CommandHandler for TestHandler {
        fn execute(&self, context: &mut dyn ExecutionContext, _args: &ParsedArgs) -> Result<()> {
            let ctx = crate::context::downcast_mut::<TestContext>(context)
                .expect("Failed to downcast context");
            ctx.executed_commands.push(self.name.clone());
            Ok(())
        }
    }

    fn create_test_registry() -> CommandRegistry {
        let mut registry = CommandRegistry::new();
        let cmd_def = CommandDefinition {
            name: "test".to_string(),
            aliases: vec!["t".to_string()],
            description: "Test command".to_string(),
            required: false,
            arguments: vec![],
            options: vec![],
            implementation: "test_handler".to_string(),
            continue_on_failure: false,
            requires_success: false,
        };
        registry
            .register_sync(
                cmd_def,
                Box::new(TestHandler {
                    name: "test".to_string(),
                }),
            )
            .unwrap();
        registry
    }

    fn make_help_config() -> CommandsConfig {
        use crate::config::schema::{CommandsConfig, Metadata};
        CommandsConfig {
            metadata: Metadata {
                version: "1.0.0".to_string(),
                prompt: "testapp".to_string(),
                prompt_suffix: " > ".to_string(),
            },
            commands: vec![CommandDefinition {
                name: "hello".to_string(),
                aliases: vec!["hi".to_string()],
                description: "Say hello".to_string(),
                required: false,
                arguments: vec![],
                options: vec![OptionDefinition {
                    name: "loud".to_string(),
                    short: Some("l".to_string()),
                    long: Some("loud".to_string()),
                    option_type: ArgumentType::Bool,
                    required: false,
                    default: Some("false".to_string()),
                    description: "Loud greeting".to_string(),
                    choices: vec![],
                    repeatable: false,
                    option_parameters: HashMap::new(),
                }],
                implementation: "hello_handler".to_string(),
                continue_on_failure: false,
                requires_success: false,
            }],
            global_options: vec![],
            directives: vec![],
        }
    }

    // ── Construction ──────────────────────────────────────────────────────────

    #[test]
    fn test_repl_interface_creation() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let repl = ReplInterface::new(registry, context, "test".to_string(), None, None);
        assert!(repl.is_ok());
    }

    #[test]
    fn test_repl_interface_creation_with_config() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let config = make_help_config();
        let repl = ReplInterface::new(registry, context, "test".to_string(), Some(config), None);
        assert!(repl.is_ok());
    }

    // ── execute_line ──────────────────────────────────────────────────────────

    #[test]
    fn test_repl_execute_line() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();
        let result = repl.execute_line("test");
        assert!(result.is_ok());
        let ctx = crate::context::downcast_ref::<TestContext>(&*repl.context).unwrap();
        assert_eq!(ctx.executed_commands, vec!["test".to_string()]);
    }

    #[test]
    fn test_repl_execute_with_alias() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();
        assert!(repl.execute_line("t").is_ok());
    }

    #[test]
    fn test_repl_execute_unknown_command() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();
        let result = repl.execute_line("unknown");
        assert!(result.is_err());
        match result.unwrap_err() {
            DynamicCliError::Parse(_) => {}
            other => panic!("Expected Parse error, got: {:?}", other),
        }
    }

    #[test]
    fn test_repl_empty_line() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();
        assert!(repl.execute_line("").is_err());
    }

    #[test]
    fn test_repl_command_with_args() {
        let mut registry = CommandRegistry::new();
        let cmd_def = CommandDefinition {
            name: "greet".to_string(),
            aliases: vec![],
            description: "Greet someone".to_string(),
            required: false,
            arguments: vec![ArgumentDefinition {
                name: "name".to_string(),
                arg_type: ArgumentType::String,
                required: true,
                description: "Name".to_string(),
                validation: vec![],
                secure: false,
            }],
            options: vec![],
            implementation: "greet_handler".to_string(),
            continue_on_failure: false,
            requires_success: false,
        };

        struct GreetHandler;
        impl crate::executor::CommandHandler for GreetHandler {
            fn execute(&self, _ctx: &mut dyn ExecutionContext, args: &ParsedArgs) -> Result<()> {
                assert_eq!(args.get_scalar("name"), Some("Alice"));
                Ok(())
            }
        }

        registry
            .register_sync(cmd_def, Box::new(GreetHandler))
            .unwrap();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();
        assert!(repl.execute_line("greet Alice").is_ok());
    }

    // ── History path ──────────────────────────────────────────────────────────

    #[test]
    fn test_repl_history_path() {
        let path = ReplInterface::get_history_path("myapp");
        if let Some(p) = path {
            let path_str = p.to_str().unwrap();
            assert!(path_str.contains("myapp"), "path should contain app name");
            assert!(
                path_str.ends_with("history"),
                "path should end with 'history', got: {}",
                path_str
            );
        }
    }

    // ── Help interception ─────────────────────────────────────────────────────

    #[test]
    fn test_try_handle_help_without_config_returns_none() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let repl = ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();
        assert!(repl.try_handle_help("--help").is_none());
        assert!(repl.try_handle_help("-h").is_none());
    }

    /// Regression test for #76: without an explicit formatter, help falls
    /// back to `DefaultHelpFormatter` instead of being skipped.
    #[test]
    fn test_try_handle_help_without_formatter_uses_default() {
        colored::control::set_override(false);
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let config = make_help_config();
        let repl =
            ReplInterface::new(registry, context, "test".to_string(), Some(config), None).unwrap();

        let formatter = DefaultHelpFormatter::new();
        let expected_app = format!(
            "{}{}\nType ':help <command>' for more information on a command.\n",
            formatter.format_app(repl.config.as_deref().unwrap()),
            formatter.format_directives(&effective_directives(&[]))
        );
        let expected_cmd =
            DefaultHelpFormatter::new().format_command(repl.config.as_deref().unwrap(), "hello");

        assert_eq!(repl.try_handle_help("--help"), Some(expected_app.clone()));
        assert_eq!(repl.try_handle_help("-h"), Some(expected_app));
        for line in ["--help hello", "-h hello", "hello --help", "hello -h"] {
            assert_eq!(
                repl.try_handle_help(line),
                Some(expected_cmd.clone()),
                "line: {line}"
            );
        }
    }

    /// Regression test for #76 through the dispatch path used by `run()`:
    /// `--help` must be handled, not reported as an unknown command.
    #[test]
    fn test_execute_line_help_without_formatter() {
        colored::control::set_override(false);
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let config = make_help_config();
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), Some(config), None).unwrap();
        assert!(repl.execute_line("--help").is_ok());
        assert!(repl.execute_line("hello --help").is_ok());
    }

    #[test]
    fn test_try_handle_help_global() {
        colored::control::set_override(false);
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let config = make_help_config();
        let repl = ReplInterface::new(
            registry,
            context,
            "test".to_string(),
            Some(config),
            Some(Box::new(DefaultHelpFormatter::new())),
        )
        .unwrap();
        let out = repl.try_handle_help("--help");
        assert!(out.is_some());
        let out = out.unwrap();
        assert!(out.contains("testapp"));
        assert!(out.contains("hello"));
    }

    #[test]
    fn test_try_handle_help_short_flag() {
        colored::control::set_override(false);
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let config = make_help_config();
        let repl = ReplInterface::new(
            registry,
            context,
            "test".to_string(),
            Some(config),
            Some(Box::new(DefaultHelpFormatter::new())),
        )
        .unwrap();
        let out = repl.try_handle_help("-h");
        assert!(out.is_some());
        assert!(out.unwrap().contains("testapp"));
    }

    #[test]
    fn test_try_handle_help_with_command_prefix() {
        colored::control::set_override(false);
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let config = make_help_config();
        let repl = ReplInterface::new(
            registry,
            context,
            "test".to_string(),
            Some(config),
            Some(Box::new(DefaultHelpFormatter::new())),
        )
        .unwrap();
        let out = repl.try_handle_help("--help hello");
        assert!(out.is_some());
        assert!(out.unwrap().contains("hello"));
        let out2 = repl.try_handle_help("-h hello");
        assert!(out2.is_some());
    }

    #[test]
    fn test_try_handle_help_command_suffix() {
        colored::control::set_override(false);
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let config = make_help_config();
        let repl = ReplInterface::new(
            registry,
            context,
            "test".to_string(),
            Some(config),
            Some(Box::new(DefaultHelpFormatter::new())),
        )
        .unwrap();
        let out = repl.try_handle_help("hello --help");
        assert!(out.is_some());
        assert!(out.unwrap().contains("hello"));
        let out2 = repl.try_handle_help("hello -h");
        assert!(out2.is_some());
    }

    #[test]
    fn test_try_handle_help_alias() {
        colored::control::set_override(false);
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let config = make_help_config();
        let repl = ReplInterface::new(
            registry,
            context,
            "test".to_string(),
            Some(config),
            Some(Box::new(DefaultHelpFormatter::new())),
        )
        .unwrap();
        let out = repl.try_handle_help("--help hi");
        assert!(out.is_some());
        assert!(out.unwrap().contains("hello"));
    }

    #[test]
    fn test_execute_line_help_intercepted() {
        colored::control::set_override(false);
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let config = make_help_config();
        let mut repl = ReplInterface::new(
            registry,
            context,
            "test".to_string(),
            Some(config),
            Some(Box::new(DefaultHelpFormatter::new())),
        )
        .unwrap();
        assert!(repl.execute_line("--help").is_ok());
    }

    #[test]
    fn test_execute_line_normal_command_still_works_with_formatter() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let config = make_help_config();
        let mut repl = ReplInterface::new(
            registry,
            context,
            "test".to_string(),
            Some(config),
            Some(Box::new(DefaultHelpFormatter::new())),
        )
        .unwrap();
        assert!(repl.execute_line("test").is_ok());
    }

    // ── Tab completion ────────────────────────────────────────────────────────

    fn default_directives() -> Arc<[DirectiveDefinition]> {
        effective_directives(&[]).into()
    }

    #[test]
    fn test_completer_commands_empty_input() {
        let registry = Arc::new(create_test_registry());
        let completer = DcliCompleter::new(Arc::clone(&registry), None, default_directives());
        let history = rustyline::history::DefaultHistory::new();
        let ctx = rustyline::Context::new(&history);
        let (_, candidates) = completer.complete("", 0, &ctx).unwrap();
        let names: Vec<&str> = candidates.iter().map(|p| p.display.as_str()).collect();
        assert!(names.contains(&"test"));
        assert!(names.contains(&"t"));
    }

    #[test]
    fn test_completer_commands_prefix_filter() {
        let registry = Arc::new(create_test_registry());
        let completer = DcliCompleter::new(Arc::clone(&registry), None, default_directives());
        let history = rustyline::history::DefaultHistory::new();
        let ctx = rustyline::Context::new(&history);
        let (_, candidates) = completer.complete("te", 2, &ctx).unwrap();
        let names: Vec<&str> = candidates.iter().map(|p| p.display.as_str()).collect();
        assert!(names.contains(&"test"));
        assert!(!names.contains(&"t"));
    }

    #[test]
    fn test_completer_flags_after_command() {
        let config = Arc::new(make_help_config());
        // Registry with "hello" command
        let mut registry = CommandRegistry::new();
        let cmd_def = make_help_config().commands.into_iter().next().unwrap();
        struct DummyHandler;
        impl crate::executor::CommandHandler for DummyHandler {
            fn execute(&self, _: &mut dyn ExecutionContext, _: &ParsedArgs) -> Result<()> {
                Ok(())
            }
        }
        registry
            .register_sync(cmd_def, Box::new(DummyHandler))
            .unwrap();
        let registry = Arc::new(registry);

        let completer = DcliCompleter::new(
            Arc::clone(&registry),
            Some(Arc::clone(&config)),
            default_directives(),
        );
        let history = rustyline::history::DefaultHistory::new();
        let ctx = rustyline::Context::new(&history);

        // "hello " → should propose --loud and -l
        let (_, candidates) = completer.complete("hello ", 6, &ctx).unwrap();
        let names: Vec<&str> = candidates.iter().map(|p| p.display.as_str()).collect();
        assert!(
            names.contains(&"--loud"),
            "expected --loud, got {:?}",
            names
        );
        assert!(names.contains(&"-l"), "expected -l, got {:?}", names);
    }

    #[test]
    fn test_completer_flags_prefix_filter() {
        let config = Arc::new(make_help_config());
        let mut registry = CommandRegistry::new();
        let cmd_def = make_help_config().commands.into_iter().next().unwrap();
        struct DummyHandler;
        impl crate::executor::CommandHandler for DummyHandler {
            fn execute(&self, _: &mut dyn ExecutionContext, _: &ParsedArgs) -> Result<()> {
                Ok(())
            }
        }
        registry
            .register_sync(cmd_def, Box::new(DummyHandler))
            .unwrap();
        let registry = Arc::new(registry);

        let completer = DcliCompleter::new(
            Arc::clone(&registry),
            Some(Arc::clone(&config)),
            default_directives(),
        );
        let history = rustyline::history::DefaultHistory::new();
        let ctx = rustyline::Context::new(&history);

        // "hello --l" → only --loud
        let (_, candidates) = completer.complete("hello --l", 9, &ctx).unwrap();
        let names: Vec<&str> = candidates.iter().map(|p| p.display.as_str()).collect();
        assert!(names.contains(&"--loud"));
        assert!(!names.contains(&"-l"));
    }

    #[test]
    fn test_completer_no_flags_for_unknown_command() {
        let config = Arc::new(make_help_config());
        let registry = Arc::new(create_test_registry());
        let completer = DcliCompleter::new(
            Arc::clone(&registry),
            Some(Arc::clone(&config)),
            default_directives(),
        );
        let history = rustyline::history::DefaultHistory::new();
        let ctx = rustyline::Context::new(&history);
        // "unknown " → empty (command not in registry)
        let (_, candidates) = completer.complete("unknown ", 8, &ctx).unwrap();
        assert!(candidates.is_empty());
    }

    // ── has_secure_arg ────────────────────────────────────────────────────────

    /// Build a registry + config with one command that has a `secure` argument.
    fn make_secure_registry_and_config() -> (CommandRegistry, CommandsConfig) {
        use crate::config::schema::{CommandsConfig, Metadata};

        let cmd_def = CommandDefinition {
            name: "login".to_string(),
            aliases: vec![],
            description: "Login command".to_string(),
            required: false,
            arguments: vec![
                ArgumentDefinition {
                    name: "username".to_string(),
                    arg_type: ArgumentType::String,
                    required: true,
                    description: "Username".to_string(),
                    validation: vec![],
                    secure: false,
                },
                ArgumentDefinition {
                    name: "password".to_string(),
                    arg_type: ArgumentType::String,
                    required: true,
                    description: "Password".to_string(),
                    validation: vec![],
                    secure: true,
                },
            ],
            options: vec![],
            implementation: "login_handler".to_string(),
            continue_on_failure: false,
            requires_success: false,
        };

        struct LoginHandler;
        impl crate::executor::CommandHandler for LoginHandler {
            fn execute(&self, _ctx: &mut dyn ExecutionContext, _args: &ParsedArgs) -> Result<()> {
                Ok(())
            }
        }

        let mut registry = CommandRegistry::new();
        registry
            .register_sync(cmd_def.clone(), Box::new(LoginHandler))
            .unwrap();

        let config = CommandsConfig {
            metadata: Metadata {
                version: "1.0.0".to_string(),
                prompt: "testapp".to_string(),
                prompt_suffix: " > ".to_string(),
            },
            commands: vec![cmd_def],
            global_options: vec![],
            directives: vec![],
        };

        (registry, config)
    }

    #[test]
    fn test_has_secure_arg_returns_false_without_config() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let repl = ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();

        let mut args = HashMap::new();
        args.insert("password".to_string(), "secret".to_string());

        assert!(!repl.has_secure_arg("login", &args));
    }

    #[test]
    fn test_has_secure_arg_returns_false_when_no_secure_field() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let config = make_help_config();
        let repl =
            ReplInterface::new(registry, context, "test".to_string(), Some(config), None).unwrap();

        let mut args = HashMap::new();
        args.insert("loud".to_string(), "true".to_string());

        assert!(!repl.has_secure_arg("hello", &args));
    }

    #[test]
    fn test_has_secure_arg_returns_true_when_secure_argument_present() {
        let (registry, config) = make_secure_registry_and_config();
        let context = Box::new(TestContext::default());
        let repl =
            ReplInterface::new(registry, context, "test".to_string(), Some(config), None).unwrap();

        let mut args = HashMap::new();
        args.insert("username".to_string(), "alice".to_string());
        args.insert("password".to_string(), "secret".to_string());

        assert!(repl.has_secure_arg("login", &args));
    }

    #[test]
    fn test_has_secure_arg_returns_false_when_only_non_secure_present() {
        let (registry, config) = make_secure_registry_and_config();
        let context = Box::new(TestContext::default());
        let repl =
            ReplInterface::new(registry, context, "test".to_string(), Some(config), None).unwrap();

        // Only username provided — password (secure) absent from parsed args.
        let mut args = HashMap::new();
        args.insert("username".to_string(), "alice".to_string());

        assert!(!repl.has_secure_arg("login", &args));
    }

    #[test]
    fn test_has_secure_arg_returns_false_for_unknown_command() {
        let (registry, config) = make_secure_registry_and_config();
        let context = Box::new(TestContext::default());
        let repl =
            ReplInterface::new(registry, context, "test".to_string(), Some(config), None).unwrap();

        let mut args = HashMap::new();
        args.insert("password".to_string(), "secret".to_string());

        assert!(!repl.has_secure_arg("nonexistent", &args));
    }

    // ── Secure argument history filtering ─────────────────────────────────────

    #[test]
    fn test_execute_line_with_secure_arg_does_not_add_to_history() {
        let (registry, config) = make_secure_registry_and_config();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), Some(config), None).unwrap();

        let result = repl.execute_line("login alice secret");
        assert!(result.is_ok());

        // The line must NOT appear in the in-memory history.
        let history = repl.editor.history();
        let in_history = (0..history.len()).any(|i| {
            history
                .get(i, rustyline::history::SearchDirection::Forward)
                .ok()
                .flatten()
                .map(|e| e.entry.as_ref() == "login alice secret")
                .unwrap_or(false)
        });
        assert!(
            !in_history,
            "secure command line must not be written to history"
        );
    }

    #[test]
    fn test_execute_line_without_secure_arg_adds_to_history() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();

        let result = repl.execute_line("test");
        assert!(result.is_ok());

        // The line must appear in the in-memory history.
        let history = repl.editor.history();
        let in_history = (0..history.len()).any(|i| {
            history
                .get(i, rustyline::history::SearchDirection::Forward)
                .ok()
                .flatten()
                .map(|e| e.entry.as_ref() == "test")
                .unwrap_or(false)
        });
        assert!(
            in_history,
            "non-secure command line must be written to history"
        );
    }

    // ── :load (#41 scope extension) ─────────────────────────────────────────

    fn write_script(content: &str) -> tempfile::NamedTempFile {
        use std::io::Write;
        let mut file = tempfile::NamedTempFile::new().expect("failed to create temp script file");
        file.write_all(content.as_bytes())
            .expect("failed to write temp script file");
        file
    }

    #[test]
    fn test_load_executes_each_line_via_handle_line() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();

        let script = write_script("test\nt\n");
        let line = format!(":load {}", script.path().display());

        assert!(repl.handle_line(&line).is_ok());

        let ctx = crate::context::downcast_ref::<TestContext>(&*repl.context).unwrap();
        assert_eq!(ctx.executed_commands, vec!["test", "test"]);
    }

    #[test]
    fn test_load_skips_blank_lines_and_comments() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();

        let script = write_script("# a comment\n\ntest\n   \n# another\n");
        let line = format!(":load {}", script.path().display());

        assert!(repl.handle_line(&line).is_ok());

        let ctx = crate::context::downcast_ref::<TestContext>(&*repl.context).unwrap();
        assert_eq!(ctx.executed_commands, vec!["test"]);
    }

    #[test]
    fn test_load_continues_past_a_failing_line() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();

        let script = write_script("test\nunknown_command\ntest\n");
        let line = format!(":load {}", script.path().display());

        // Unlike CliInterface::run_script(Abort), :load never returns Err
        // just because a line inside it failed — the failure is displayed
        // inline and the load proceeds to the next line.
        let result = repl.handle_line(&line);
        assert!(result.is_ok());

        let ctx = crate::context::downcast_ref::<TestContext>(&*repl.context).unwrap();
        assert_eq!(ctx.executed_commands, vec!["test", "test"]);
    }

    #[test]
    fn test_load_missing_path_argument_is_an_error() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();

        let result = repl.handle_line(":load");
        assert!(result.is_err());
    }

    #[test]
    fn test_load_missing_file_is_an_error() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();

        let result = repl.handle_line(":load /nonexistent/path/to/script.txt");
        assert!(result.is_err());
    }

    #[test]
    fn test_load_line_itself_is_not_added_to_history() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();

        let script = write_script("test\n");
        let line = format!(":load {}", script.path().display());
        assert!(repl.handle_line(&line).is_ok());

        let history = repl.editor.history();
        let load_in_history = (0..history.len()).any(|i| {
            history
                .get(i, rustyline::history::SearchDirection::Forward)
                .ok()
                .flatten()
                .map(|e| e.entry.starts_with(":load"))
                .unwrap_or(false)
        });
        assert!(
            !load_in_history,
            ":load line itself must not be written to history"
        );
    }

    // ========================================================================
    // No accidental scope leak from CLI chaining — DD-026 (#52), #56
    // ========================================================================

    #[test]
    fn test_repl_line_is_never_chained_across_multiple_commands() {
        // execute_line() (and, through it, :load) goes through
        // ReplParser::parse_line() -> CliParser::parse() (the scalar,
        // method predating DD-026 (#52)) — never CliInterface::dispatch()'s
        // segmentation. A line naming two registered commands back to
        // back must therefore still be read as ONE command whose arity
        // is exceeded by the second name, exactly as before chaining
        // existed for the CLI — not as two chained commands.
        let mut registry = CommandRegistry::new();
        for name in ["first", "second"] {
            let cmd_def = CommandDefinition {
                name: name.to_string(),
                aliases: vec![],
                description: format!("Test command {}", name),
                required: false,
                arguments: vec![ArgumentDefinition {
                    name: "value".to_string(),
                    arg_type: ArgumentType::String,
                    required: true,
                    description: "Value".to_string(),
                    validation: vec![],
                    secure: false,
                }],
                options: vec![],
                implementation: format!("{}_handler", name),
                continue_on_failure: false,
                requires_success: false,
            };
            registry
                .register_sync(
                    cmd_def,
                    Box::new(TestHandler {
                        name: name.to_string(),
                    }),
                )
                .unwrap();
        }

        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();

        // "first" has arity 1; "1" fills it, leaving "second" as a
        // genuine overflow — never a second, chained command.
        let result = repl.execute_line("first 1 second");

        assert!(result.is_err());
        match result.unwrap_err() {
            DynamicCliError::Parse(ParseError::TooManyArguments { command, .. }) => {
                assert_eq!(command, "first");
            }
            other => panic!("Expected TooManyArguments error, got: {:?}", other),
        }

        // Neither command actually ran — in particular, "second" was
        // never silently executed as a chained segment.
        let ctx = crate::context::downcast_ref::<TestContext>(&*repl.context).unwrap();
        assert!(ctx.executed_commands.is_empty());
    }

    // ========================================================================
    // Prompt suffix bugfix + multi-line continuation prompt — DD-027 (#48), #67
    // ========================================================================

    #[test]
    fn test_prompt_uses_default_suffix_without_config() {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let repl = ReplInterface::new(registry, context, "myapp".to_string(), None, None).unwrap();

        // No config supplied: falls back to the schema's own default,
        // not an independently hardcoded literal.
        assert_eq!(repl.prompt, "myapp > ");
    }

    #[test]
    fn test_prompt_honours_configured_suffix() {
        // Regression test for the bug where `config.metadata.prompt_suffix`
        // was silently ignored in favour of a hardcoded " > ".
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut config = make_help_config();
        config.metadata.prompt_suffix = " $ ".to_string();

        let repl =
            ReplInterface::new(registry, context, "rpn".to_string(), Some(config), None).unwrap();

        assert_eq!(repl.prompt, "rpn $ ");
    }

    #[test]
    fn test_effective_prompt_multiline_default_derivation() {
        // The exact example from the closing checklist of DD-027 (#48): default
        // suffix " > " -> multi-line default "...> ".
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let repl = ReplInterface::new(registry, context, "rpn".to_string(), None, None).unwrap();

        assert_eq!(repl.prompt, "rpn > ");
        assert_eq!(repl.effective_prompt_multiline(), "...> ");
    }

    #[test]
    fn test_effective_prompt_multiline_uses_configured_suffix() {
        // The multi-line default must track a *custom* suffix too, not just
        // the " > " default — same bug class as the main prompt. Leading
        // whitespace of the suffix is still stripped for the default "..."
        // base, same as the " > " case.
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut config = make_help_config();
        config.metadata.prompt_suffix = " $ ".to_string();

        let repl =
            ReplInterface::new(registry, context, "rpn".to_string(), Some(config), None).unwrap();

        assert_eq!(repl.effective_prompt_multiline(), "...$ ");
    }

    #[test]
    fn test_with_prompt_multiline_overrides_base_only() {
        // Overriding only replaces the "..." base — the configured suffix
        // is still appended automatically.
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut config = make_help_config();
        config.metadata.prompt_suffix = " $ ".to_string();

        let repl = ReplInterface::new(registry, context, "rpn".to_string(), Some(config), None)
            .unwrap()
            .with_prompt_multiline("_ _ _".to_string());

        assert_eq!(repl.effective_prompt_multiline(), "_ _ _ $ ");
    }

    // ========================================================================
    // `\`-continuation accumulation logic — DD-027 (#48), #69
    // ========================================================================

    #[test]
    fn test_accumulate_line_single_line_no_continuation() {
        let mut buffer: Vec<String> = Vec::new();
        let result = ReplInterface::accumulate_line(&mut buffer, "test");

        assert_eq!(result, Some("test".to_string()));
        assert!(buffer.is_empty());
    }

    #[test]
    fn test_accumulate_line_trailing_backslash_buffers_and_returns_none() {
        let mut buffer: Vec<String> = Vec::new();
        let result = ReplInterface::accumulate_line(&mut buffer, "push \\");

        assert_eq!(result, None);
        assert_eq!(buffer, vec!["push".to_string()]);
    }

    #[test]
    fn test_accumulate_line_multi_fragment_reconstruction() {
        // Three lines: two continued, one final — mirrors the example in
        // DD-027 (#48) of a command whose options span several REPL lines.
        let mut buffer: Vec<String> = Vec::new();

        assert_eq!(
            ReplInterface::accumulate_line(&mut buffer, "config \\"),
            None
        );
        assert_eq!(
            ReplInterface::accumulate_line(&mut buffer, "--format model \\"),
            None
        );
        let result = ReplInterface::accumulate_line(&mut buffer, "source=model.yml");

        assert_eq!(
            result,
            Some("config --format model source=model.yml".to_string())
        );
        // The buffer is drained once the command completes.
        assert!(buffer.is_empty());
    }

    #[test]
    fn test_accumulate_line_strips_marker_and_surrounding_whitespace() {
        // The `\` marker and the whitespace immediately before it are never
        // part of the reconstructed line — fragments are joined by exactly
        // one space, not whatever spacing the user typed.
        let mut buffer: Vec<String> = Vec::new();
        ReplInterface::accumulate_line(&mut buffer, "test   \\");
        let result = ReplInterface::accumulate_line(&mut buffer, "  arg");

        assert_eq!(result, Some("test arg".to_string()));
    }

    #[test]
    fn test_run_multiline_reconstruction_reaches_execute_line_once() {
        // Simulates what `run()` does with each `readline()` result,
        // without needing a real terminal: feed the same raw lines a real
        // session would produce, dispatch only once the buffer completes,
        // exactly as `run()` itself does.
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();

        let mut buffer: Vec<String> = Vec::new();
        assert_eq!(ReplInterface::accumulate_line(&mut buffer, "te \\"), None);
        let line = ReplInterface::accumulate_line(&mut buffer, "st").unwrap();
        assert_eq!(line, "te st");

        // "te st" isn't a registered command name — proves the reconstructed
        // line, not raw fragments, is what actually gets dispatched.
        let result = repl.execute_line(&line);
        assert!(result.is_err());
    }

    #[test]
    fn test_load_line_ending_in_backslash_is_not_continued() {
        // :load bypasses run()'s accumulation buffer entirely — each script
        // line goes straight to handle_line(), one at a time. A trailing
        // `\` in a script has no special meaning there: DD-027 (#48) scopes
        // continuation to the interactive `run()` loop only.
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();

        let script = write_script("test \\\ntest\n");
        let line = format!(":load {}", script.path().display());

        // The first line ("test \") is dispatched as-is — "\" is an
        // unexpected extra positional argument for the zero-arity "test"
        // command, not silently joined with the next line.
        assert!(repl.handle_line(&line).is_ok());

        let ctx = crate::context::downcast_ref::<TestContext>(&*repl.context).unwrap();
        // Only the second, unadorned "test" line actually executed.
        assert_eq!(ctx.executed_commands, vec!["test"]);
    }

    // ── Directives (#94) ─────────────────────────────────────────────────────

    use crate::config::directive::DirectiveDefinition;

    fn repl_with(
        config: Option<CommandsConfig>,
        formatter: Option<Box<dyn HelpFormatter>>,
    ) -> ReplInterface {
        let registry = create_test_registry();
        let context = Box::new(TestContext::default());
        ReplInterface::new(registry, context, "test".to_string(), config, formatter).unwrap()
    }

    /// `make_help_config()` with the given directive overrides
    fn config_with_directives(directives: Vec<DirectiveDefinition>) -> CommandsConfig {
        let mut config = make_help_config();
        config.directives = directives;
        config
    }

    fn override_directive(
        implementation: ReplDirective,
        name: &str,
        aliases: &[&str],
    ) -> DirectiveDefinition {
        DirectiveDefinition {
            implementation,
            name: name.to_string(),
            aliases: aliases.iter().map(|a| a.to_string()).collect(),
            description: "Custom".to_string(),
        }
    }

    fn history_len(repl: &ReplInterface) -> usize {
        repl.editor.history().len()
    }

    fn executed(repl: &ReplInterface) -> Vec<String> {
        crate::context::downcast_ref::<TestContext>(&*repl.context)
            .unwrap()
            .executed_commands
            .clone()
    }

    /// Unwrap an `InvalidSyntax` error into `(details, hint)`
    fn invalid_syntax(result: Result<SessionControl>) -> (String, String) {
        match result {
            Err(DynamicCliError::Parse(ParseError::InvalidSyntax { details, hint })) => {
                (details, hint.unwrap_or_default())
            }
            other => panic!("Expected InvalidSyntax error, got {:?}", other),
        }
    }

    /// Unwrap an `UnknownCommand` error into its suggestions
    fn unknown_command_suggestions(result: Result<SessionControl>) -> Vec<String> {
        match result {
            Err(DynamicCliError::Parse(ParseError::UnknownCommand { suggestions, .. })) => {
                suggestions
            }
            other => panic!("Expected UnknownCommand error, got {:?}", other),
        }
    }

    /// Unwrap an `UnknownCommand` error into its hint
    fn unknown_command_hint(result: Result<SessionControl>) -> String {
        match result {
            Err(DynamicCliError::Parse(ParseError::UnknownCommand { hint, .. })) => {
                hint.expect("the REPL sets the hint")
            }
            other => panic!("Expected UnknownCommand error, got {:?}", other),
        }
    }

    #[test]
    fn test_directive_table_defaults_without_config() {
        let repl = repl_with(None, None);
        assert_eq!(&repl.directives[..], effective_directives(&[]).as_slice());
        assert_eq!(repl.resolve_directive("q"), Some(ReplDirective::Quit));
        assert_eq!(repl.resolve_directive("?"), Some(ReplDirective::Help));
        assert_eq!(repl.resolve_directive("test"), None);
    }

    #[test]
    fn test_directive_help_forms_without_formatter() {
        colored::control::set_override(false);
        let mut repl = repl_with(Some(make_help_config()), None);
        for line in [
            ":help",
            ":h",
            ":?",
            ":help hello",
            ":h hi",
            "  :help  hello  ",
        ] {
            assert_eq!(
                repl.handle_line(line).unwrap(),
                SessionControl::Continue,
                "{}",
                line
            );
        }
    }

    #[test]
    fn test_directive_help_forms_with_formatter() {
        colored::control::set_override(false);
        let mut repl = repl_with(
            Some(make_help_config()),
            Some(Box::new(DefaultHelpFormatter::new())),
        );
        for line in [":help", ":h", ":?", ":help hello"] {
            assert_eq!(
                repl.handle_line(line).unwrap(),
                SessionControl::Continue,
                "{}",
                line
            );
        }
    }

    #[test]
    fn test_directive_help_renders_like_help_flag() {
        colored::control::set_override(false);
        let repl = repl_with(Some(make_help_config()), None);
        assert_eq!(repl.render_help(None), repl.try_handle_help("--help"));
        assert_eq!(
            repl.render_help(Some("hello")),
            repl.try_handle_help("--help hello")
        );
    }

    // ── Help hints (#86) ─────────────────────────────────────────────────────

    #[test]
    fn test_unknown_command_hint_names_help_directive() {
        let mut repl = repl_with(Some(make_help_config()), None);
        assert_eq!(
            unknown_command_hint(repl.handle_line("frobnicate")),
            "Type ':help' for available commands"
        );
    }

    #[test]
    fn test_unknown_command_hint_without_config() {
        // The hint does not depend on the configuration.
        let mut repl = repl_with(None, None);
        assert_eq!(
            unknown_command_hint(repl.handle_line("frobnicate")),
            "Type ':help' for available commands"
        );
    }

    #[test]
    fn test_unknown_command_hint_with_directive_suggestion() {
        colored::control::set_override(false);
        let mut repl = repl_with(Some(make_help_config()), None);
        let error = repl.handle_line("quit").unwrap_err();
        let formatted = crate::error::format_error(&error);

        let suggestion_at = formatted.find(":quit").expect("directive suggested");
        let hint_at = formatted
            .find("Type ':help' for available commands")
            .expect("hint shown");
        assert!(suggestion_at < hint_at, "{}", formatted);
    }

    #[test]
    fn test_help_hints_use_translated_help_directive() {
        colored::control::set_override(false);
        let mut repl = repl_with(
            Some(config_with_directives(vec![override_directive(
                ReplDirective::Help,
                "aide",
                &["?"],
            )])),
            None,
        );

        assert_eq!(
            unknown_command_hint(repl.handle_line("frobnicate")),
            "Type ':aide' for available commands"
        );

        let app_help = repl.render_help(None).unwrap();
        assert!(
            app_help.ends_with("\nType ':aide <command>' for more information on a command.\n"),
            "{}",
            app_help
        );
        assert!(!app_help.contains(":help"), "{}", app_help);
    }

    #[test]
    fn test_app_help_footer_names_help_directive() {
        colored::control::set_override(false);
        let repl = repl_with(Some(make_help_config()), None);
        let config = repl.config.as_deref().unwrap();

        let formatter = DefaultHelpFormatter::new();
        assert_eq!(
            repl.render_help(None).unwrap(),
            format!(
                "{}{}\nType ':help <command>' for more information on a command.\n",
                formatter.format_app(config),
                formatter.format_directives(&repl.directives)
            )
        );
        // Per-command help has no footer.
        assert_eq!(
            repl.render_help(Some("hello")).unwrap(),
            DefaultHelpFormatter::new().format_command(config, "hello")
        );
    }

    #[test]
    fn test_directive_help_without_config_is_not_available() {
        let mut repl = repl_with(None, None);
        let err = repl.handle_line(":help").unwrap_err();
        assert!(err.to_string().contains("help is not available"), "{}", err);
    }

    #[test]
    fn test_directive_help_with_two_arguments_is_a_usage_error() {
        let mut repl = repl_with(Some(make_help_config()), None);
        let (details, hint) = invalid_syntax(repl.handle_line(":h hello extra"));
        assert!(details.contains("`:h`"), "{}", details);
        assert_eq!(hint, "Usage: :help [command]");
    }

    #[test]
    fn test_directive_quit_and_exit_leave() {
        let mut repl = repl_with(None, None);
        let save = SessionControl::Leave { save_history: true };
        let discard = SessionControl::Leave {
            save_history: false,
        };
        assert_eq!(repl.handle_line(":quit").unwrap(), save);
        assert_eq!(repl.handle_line(":q").unwrap(), save);
        assert_eq!(repl.handle_line(":exit").unwrap(), discard);
    }

    #[test]
    fn test_directive_quit_with_argument_is_a_usage_error() {
        let mut repl = repl_with(None, None);
        let (details, hint) = invalid_syntax(repl.handle_line(":q now"));
        assert!(details.contains("takes no argument"), "{}", details);
        assert_eq!(hint, "Usage: :quit");
    }

    #[test]
    fn test_directive_load_without_path_shows_usage() {
        let mut repl = repl_with(None, None);
        let (details, hint) = invalid_syntax(repl.handle_line(":load"));
        assert!(details.contains("requires a file path"), "{}", details);
        assert_eq!(hint, "Usage: :load <path>");
    }

    // rustyline's `save_history()` sets the process-wide umask to 0o177
    // while it creates the history file. A directory created meanwhile by
    // another test thread, such as a `tempfile::tempdir()`, loses its
    // search bit, and creating a file inside it fails with EACCES. The
    // tests below create a directory or save the history, so each one holds
    // this lock for its whole body.
    static HISTORY_FILE_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());

    fn history_file_lock() -> std::sync::MutexGuard<'static, ()> {
        HISTORY_FILE_LOCK
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
    }

    #[test]
    fn test_end_session_with_save_writes_history_file() {
        let _lock = history_file_lock();
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("history");
        let mut repl = repl_with(None, None);
        repl.history_path = Some(path.clone());

        assert!(repl.handle_line("test").is_ok());
        repl.end_session(true);

        let content = std::fs::read_to_string(&path).unwrap();
        assert!(content.lines().any(|l| l == "test"), "{}", content);
    }

    #[test]
    fn test_end_session_without_save_leaves_history_file_unchanged() {
        let _lock = history_file_lock();
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("history");
        std::fs::write(&path, "previous\n").unwrap();
        let mut repl = repl_with(None, None);
        repl.history_path = Some(path.clone());

        assert!(repl.handle_line("test").is_ok());
        repl.end_session(false);

        assert_eq!(std::fs::read_to_string(&path).unwrap(), "previous\n");
    }

    #[test]
    fn test_drop_does_not_write_history_file() {
        let _lock = history_file_lock();
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("history");
        let mut repl = repl_with(None, None);
        repl.history_path = Some(path.clone());

        assert!(repl.handle_line("test").is_ok());
        drop(repl);

        assert!(!path.exists());
    }

    #[test]
    fn test_directive_lines_are_not_added_to_history() {
        colored::control::set_override(false);
        let mut repl = repl_with(Some(make_help_config()), None);
        // `new()` loads the history file of the "test" prompt, if any.
        let before = history_len(&repl);
        for line in [":help", ":quit", ":exit", ":unknown"] {
            let _ = repl.handle_line(line);
        }
        assert_eq!(history_len(&repl), before);
    }

    #[test]
    fn test_bare_quit_and_exit_no_longer_leave() {
        let mut repl = repl_with(None, None);

        let suggestions = unknown_command_suggestions(repl.handle_line("quit"));
        assert_eq!(suggestions.first().map(String::as_str), Some(":quit"));

        let suggestions = unknown_command_suggestions(repl.handle_line("exit"));
        assert_eq!(suggestions.first().map(String::as_str), Some(":exit"));

        let suggestions = unknown_command_suggestions(repl.handle_line("q"));
        assert_eq!(suggestions.first().map(String::as_str), Some(":q"));
    }

    #[test]
    fn test_unknown_command_unrelated_to_directives_gets_no_directive() {
        let mut repl = repl_with(None, None);
        let suggestions = unknown_command_suggestions(repl.handle_line("frobnicate"));
        assert!(suggestions.iter().all(|s| !s.starts_with(':')));
    }

    #[test]
    fn test_application_command_named_like_a_directive_runs() {
        let mut registry = create_test_registry();
        let exit = CommandDefinition {
            name: "exit".to_string(),
            aliases: vec![],
            description: "Application exit command".to_string(),
            required: false,
            arguments: vec![],
            options: vec![],
            implementation: "exit_handler".to_string(),
            continue_on_failure: false,
            requires_success: false,
        };
        registry
            .register_sync(
                exit,
                Box::new(TestHandler {
                    name: "exit".to_string(),
                }),
            )
            .unwrap();
        let context = Box::new(TestContext::default());
        let mut repl =
            ReplInterface::new(registry, context, "test".to_string(), None, None).unwrap();

        assert_eq!(repl.handle_line("exit").unwrap(), SessionControl::Continue);
        assert_eq!(executed(&repl), vec!["exit"]);
        // The directive stays reachable with its prefix.
        assert_eq!(
            repl.handle_line(":exit").unwrap(),
            SessionControl::Leave {
                save_history: false
            }
        );
    }

    #[test]
    fn test_translated_directive_names_replace_defaults() {
        let mut repl = repl_with(
            Some(config_with_directives(vec![
                override_directive(ReplDirective::Quit, "quitter", &[]),
                override_directive(ReplDirective::Load, "charger", &["c"]),
            ])),
            None,
        );

        assert_eq!(
            repl.handle_line(":quitter").unwrap(),
            SessionControl::Leave { save_history: true }
        );
        // `quit` and its default alias `q` no longer match.
        assert!(repl.handle_line(":quit").is_err());
        assert!(repl.handle_line(":q").is_err());
        // Untouched directives keep their defaults.
        assert_eq!(
            repl.handle_line(":exit").unwrap(),
            SessionControl::Leave {
                save_history: false
            }
        );

        let script = write_script("test\n");
        let line = format!(":c {}", script.path().display());
        assert!(repl.handle_line(&line).is_ok());
        assert_eq!(executed(&repl), vec!["test"]);

        let (_, hint) = invalid_syntax(repl.handle_line(":charger"));
        assert_eq!(hint, "Usage: :charger <path>");

        let suggestions = unknown_command_suggestions(repl.handle_line("quitter"));
        assert_eq!(suggestions.first().map(String::as_str), Some(":quitter"));
        // `quit` is no longer a directive name: no directive suggested.
        let suggestions = unknown_command_suggestions(repl.handle_line("quit"));
        assert!(!suggestions.iter().any(|s| s == ":quit"));
    }

    #[test]
    fn test_unknown_directive_lists_effective_directives() {
        let mut repl = repl_with(
            Some(config_with_directives(vec![override_directive(
                ReplDirective::Help,
                "aide",
                &[],
            )])),
            None,
        );

        let (details, hint) = invalid_syntax(repl.handle_line(":foo"));
        assert_eq!(details, "Unknown directive ':foo'");
        assert_eq!(hint, "Available directives: :aide, :load, :quit, :exit");

        let (details, _) = invalid_syntax(repl.handle_line(":"));
        assert_eq!(details, "Unknown directive ':'");
    }

    // ── Directive discoverability (#95) ──────────────────────────────────────

    /// Display strings and start offset of the completion of `line`, with
    /// the cursor at its end.
    fn complete_with(directives: Arc<[DirectiveDefinition]>, line: &str) -> (usize, Vec<String>) {
        let completer = DcliCompleter::new(Arc::new(create_test_registry()), None, directives);
        let history = rustyline::history::DefaultHistory::new();
        let ctx = rustyline::Context::new(&history);
        let (start, candidates) = completer.complete(line, line.len(), &ctx).unwrap();
        (
            start,
            candidates
                .into_iter()
                .map(|pair| pair.replacement)
                .collect(),
        )
    }

    #[test]
    fn test_completer_colon_lists_all_directives() {
        let (start, names) = complete_with(default_directives(), ":");
        assert_eq!(start, 0);
        assert_eq!(
            names,
            vec![":?", ":exit", ":h", ":help", ":load", ":q", ":quit"]
        );
    }

    #[test]
    fn test_completer_directive_prefix() {
        assert_eq!(complete_with(default_directives(), ":he").1, vec![":help"]);
        assert_eq!(
            complete_with(default_directives(), ":q").1,
            vec![":q", ":quit"]
        );
        assert!(complete_with(default_directives(), ":zz").1.is_empty());
        // Leading spaces: the replacement starts at the token.
        assert_eq!(
            complete_with(default_directives(), "  :lo"),
            (2, vec![":load".to_string()])
        );
    }

    #[test]
    fn test_completer_directives_follow_configuration() {
        let table: Arc<[DirectiveDefinition]> =
            effective_directives(&[override_directive(ReplDirective::Help, "aide", &["a"])]).into();
        assert_eq!(
            complete_with(Arc::clone(&table), ":a").1,
            vec![":a", ":aide"]
        );
        assert!(complete_with(table, ":h").1.is_empty());
    }

    #[test]
    fn test_completer_commands_unchanged_by_directives() {
        // No `:` candidates without a leading `:`; directive arguments are
        // not completed.
        let (_, names) = complete_with(default_directives(), "");
        assert!(names.iter().all(|n| !n.starts_with(':')), "{:?}", names);
        assert!(names.contains(&"test".to_string()));
        assert!(complete_with(default_directives(), ":help ").1.is_empty());
    }

    #[test]
    fn test_completer_shares_repl_directive_table() {
        let repl = repl_with(
            Some(config_with_directives(vec![override_directive(
                ReplDirective::Quit,
                "quitter",
                &[],
            )])),
            None,
        );
        let helper = repl.editor.helper().expect("helper installed");
        assert!(Arc::ptr_eq(&helper.completer.directives, &repl.directives));
    }

    #[test]
    fn test_app_help_lists_directives_before_footer() {
        colored::control::set_override(false);
        let repl = repl_with(Some(make_help_config()), None);
        let help = repl.render_help(None).unwrap();

        let commands_at = help.find("COMMANDS:").expect("commands");
        let directives_at = help.find("DIRECTIVES:").expect("directives");
        let footer_at = help.find("Type ':help <command>'").expect("footer");
        assert!(
            commands_at < directives_at && directives_at < footer_at,
            "{}",
            help
        );
        for usage in [":help [command]", ":load <path>", ":quit", ":exit"] {
            assert!(help.contains(usage), "{}", help);
        }
    }

    #[test]
    fn test_app_help_lists_translated_directives() {
        colored::control::set_override(false);
        let repl = repl_with(
            Some(config_with_directives(vec![
                override_directive(ReplDirective::Help, "aide", &["?"]),
                override_directive(ReplDirective::Load, "charger", &[]),
            ])),
            None,
        );
        let help = repl.render_help(None).unwrap();

        assert!(help.contains(":aide [command]"), "{}", help);
        assert!(help.contains("[aliases: :?]"), "{}", help);
        assert!(help.contains(":charger <path>"), "{}", help);
        assert!(!help.contains(":help"), "{}", help);
        assert!(!help.contains(":load"), "{}", help);
        // `--help` in the REPL renders the same output.
        assert_eq!(Some(help), repl.try_handle_help("--help"));
    }

    #[test]
    fn test_app_help_uses_custom_directive_listing() {
        struct ListingFormatter;
        impl HelpFormatter for ListingFormatter {
            fn format_app(&self, _: &CommandsConfig) -> String {
                "APP\n".to_string()
            }
            fn format_command(&self, _: &CommandsConfig, command: &str) -> String {
                command.to_string()
            }
            fn format_directives(&self, directives: &[DirectiveDefinition]) -> String {
                let names: Vec<&str> = directives.iter().map(|d| d.name.as_str()).collect();
                format!("DIR {}\n", names.join(","))
            }
        }

        colored::control::set_override(false);
        let repl = repl_with(Some(make_help_config()), Some(Box::new(ListingFormatter)));
        assert_eq!(
            repl.render_help(None).unwrap(),
            "APP\nDIR help,load,quit,exit\n\
             \nType ':help <command>' for more information on a command.\n"
        );
    }

    #[test]
    fn test_command_help_has_no_directive_list() {
        colored::control::set_override(false);
        let repl = repl_with(Some(make_help_config()), None);
        let help = repl.render_help(Some("hello")).unwrap();
        assert!(!help.contains("DIRECTIVES:"), "{}", help);
    }

    #[test]
    fn test_load_refuses_leaving_directives_and_runs_other_lines() {
        colored::control::set_override(false);
        let mut repl = repl_with(Some(make_help_config()), None);

        let script = write_script("test\n:quit\n:q\n:exit\n:help\ntest\n");
        let line = format!(":load {}", script.path().display());

        assert_eq!(repl.handle_line(&line).unwrap(), SessionControl::Continue);
        assert_eq!(executed(&repl), vec!["test", "test"]);
    }
}