victauri_plugin/

lib.rs

#![deny(missing_docs)]
// In RELEASE builds the entire MCP server is gated out via `#[cfg(debug_assertions)]`
// (`init()` is a zero-cost no-op), so the imports/constants/helpers it uses are
// intentionally dead. Don't fail a `-Dwarnings` release build on that expected
// dead code — without this, `RUSTFLAGS=-Dwarnings cargo build --release` errors.
#![cfg_attr(not(debug_assertions), allow(unused_imports, dead_code))]
//! Victauri — full-stack introspection for Tauri apps via an embedded MCP server.
//!
//! Add this plugin to your Tauri app for AI-agent-driven testing and debugging:
//! DOM snapshots, IPC tracing, cross-boundary verification, and more tools —
//! all accessible over the Model Context Protocol.
//!
//! # Quick Start
//!
//! ```ignore
//! tauri::Builder::default()
//!     .plugin(victauri_plugin::init())
//!     .run(tauri::generate_context!())
//!     .unwrap();
//! ```
//!
//! In debug builds this starts an MCP server on port 7373. In release builds
//! the plugin is a no-op with zero overhead.
//!
//! # Configuration
//!
//! Authentication is **enabled by default** with an auto-generated Bearer token
//! written to the per-user discovery directory (`<root>/<pid>/token`; the root is `%TEMP%\victauri` on
//! Windows, and on Unix `$XDG_RUNTIME_DIR/victauri`, `<temp>/victauri-<uid>` or
//! `~/.local/state/victauri`) for client
//! auto-discovery. The MCP
//! server listens on `127.0.0.1` only and is gated behind `#[cfg(debug_assertions)]`.
//! Use `.auth_token("...")` for a fixed token, or `.auth_disabled()` to opt out.
//!
//! ```ignore
//! tauri::Builder::default()
//!     .plugin(
//!         victauri_plugin::VictauriBuilder::new()
//!             .port(8080)
//!             .strict_privacy_mode()
//!             .build(),
//!     )
//!     .run(tauri::generate_context!())
//!     .unwrap();
//! ```

/// Runtime-erased webview bridge trait and its Tauri implementation.
pub mod bridge;
/// Backend database access (`SQLite` read-only queries).
///
/// Internal: reached through the `query_db` / `introspect db_health` tools. Not
/// part of the supported API.
#[cfg(feature = "sqlite")]
#[doc(hidden)]
pub mod database;
pub mod error;
/// JS bridge script generation for webview injection.
///
/// Internal: public only so the crate's own integration tests can exercise the
/// generated script. Not part of the supported API.
#[doc(hidden)]
pub mod js_bridge;
/// MCP server, tool handler, and parameter types.
pub mod mcp;
mod memory;
/// Privacy controls: command allowlists, blocklists, and tool disabling.
pub mod privacy;

/// Compose captured frames into a single contact-sheet PNG ("filmstrip").
pub(crate) mod filmstrip;
/// Output redaction for API keys, tokens, emails, and sensitive JSON keys.
///
/// Public because [`privacy::PrivacyConfig::redactor`] exposes a [`redaction::Redactor`].
pub mod redaction;
/// Screencast ring buffer backing the `trace` tool.
///
/// Internal: public only because [`VictauriState::screencast`] is. Not part of
/// the supported API.
#[doc(hidden)]
pub mod screencast;
pub(crate) mod screenshot;
mod tools;

/// Bearer-token authentication, rate limiting, and security middlewares.
pub mod auth;
/// Backend introspection and chaos engineering (profiling, fault injection, contracts).
pub mod introspection;

use std::collections::{HashMap, HashSet};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, AtomicU16, AtomicU64};
use tauri::plugin::{Builder, TauriPlugin};
use tauri::{Listener, Manager, RunEvent, Runtime};
use tokio::sync::{Mutex, oneshot, watch};
use victauri_core::{CommandRegistry, EventLog, EventRecorder};

pub use error::BuilderError;
pub use privacy::PrivacyProfile;

pub use victauri_core::CommandInfo;
pub use victauri_macros::inspectable;

/// Register command schemas with the Victauri plugin at app setup time.
///
/// Pass the `__schema()` function calls generated by `#[inspectable]`.
/// This populates the `CommandRegistry` so that `get_registry`, `resolve_command`,
/// and `detect_ghost_commands` return real results.
///
/// # Example
///
/// ```rust,ignore
/// use victauri_plugin::register_commands;
///
/// .setup(|app| {
///     register_commands!(app,
///         greet__schema(),
///         increment__schema(),
///         add_todo__schema(),
///     );
///     Ok(())
/// })
/// ```
#[macro_export]
macro_rules! register_commands {
    ($app:expr, $($schema_call:expr),+ $(,)?) => {{
        // `try_state` (not `state`) so this is a no-op in RELEASE builds: there
        // `init()` returns a no-op plugin that never manages `VictauriState`, and
        // `state()` would PANIC on the missing type. Registration is debug-only.
        if let Some(state) = $app.try_state::<std::sync::Arc<$crate::VictauriState>>() {
            $(
                state.registry.register($schema_call);
            )+
        }
    }};
}

const DEFAULT_PORT: u16 = 7373;
const DEFAULT_EVENT_CAPACITY: usize = 10_000;
const DEFAULT_RECORDER_CAPACITY: usize = 50_000;
const DEFAULT_EVAL_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
const MAX_EVENT_CAPACITY: usize = 1_000_000;
const MAX_RECORDER_CAPACITY: usize = 1_000_000;
const MAX_EVAL_TIMEOUT_SECS: u64 = 300;

/// Map of pending JavaScript eval callbacks, keyed by request ID.
/// Each entry holds a oneshot sender that resolves when the webview returns a result.
///
/// Internal plumbing (the type of [`VictauriState::pending_evals`]); not part of
/// the supported API.
#[doc(hidden)]
pub type PendingCallbacks = Arc<Mutex<HashMap<String, oneshot::Sender<String>>>>;

/// A reserved [`PendingCallbacks`] entry, removed when the guard is dropped.
///
/// Every exit path of an eval must release its slot, including the one no code runs on: a REST
/// tool call executes inside the axum future, so a client that disconnects or times out DROPS
/// the call mid-wait. Removing the entry only on the timeout/error paths leaked it then, and 100
/// leaked entries failed every later eval with "too many concurrent" until the app restarted.
pub(crate) struct PendingSlot {
    map: PendingCallbacks,
    id: String,
}

impl PendingSlot {
    /// Insert `tx` under `id` into an already-locked map (the caller checked the ceilings under
    /// the same lock).
    pub(crate) fn insert(
        map: &PendingCallbacks,
        locked: &mut HashMap<String, oneshot::Sender<String>>,
        id: String,
        tx: oneshot::Sender<String>,
    ) -> Self {
        locked.insert(id.clone(), tx);
        Self {
            map: Arc::clone(map),
            id,
        }
    }

    /// The reserved eval id.
    pub(crate) fn id(&self) -> &str {
        &self.id
    }

    /// Record which window this eval's result must come from: `Some(label)` for that window,
    /// `None` for the default window (resolved when the result arrives). Call before the eval
    /// is delivered — a result for an unbound eval is refused (see [`eval_result_accepted`]).
    /// May be called again to narrow `None` to the label the eval actually resolved to.
    pub(crate) fn bind_window(&self, label: Option<&str>) {
        let target = label.map_or(EvalTarget::DefaultWindow, |l| {
            EvalTarget::Window(l.to_string())
        });
        eval_targets().insert(self.id.clone(), target);
    }
}

/// The window an eval's result must come from.
#[derive(Clone, Debug, PartialEq, Eq)]
enum EvalTarget {
    /// This window.
    Window(String),
    /// The default window, as resolved when the result arrives.
    DefaultWindow,
}

/// Eval id -> the window its result must come from (entries live as long as their
/// [`PendingSlot`]). Process-wide: eval ids are UUIDs, unique across every state.
static EVAL_TARGETS: std::sync::LazyLock<std::sync::Mutex<HashMap<String, EvalTarget>>> =
    std::sync::LazyLock::new(Default::default);

fn eval_targets() -> std::sync::MutexGuard<'static, HashMap<String, EvalTarget>> {
    EVAL_TARGETS
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner)
}

/// Whether an eval result for `id` arriving from webview `caller` may be delivered: only from
/// the window the eval was sent to (R5B-EVALWIN1). `default_label` resolves the default window
/// (only called for an eval sent to it). A result for an id with no binding — not a pending eval,
/// or one that was never bound — is refused.
pub(crate) fn eval_result_accepted(
    id: &str,
    caller: &str,
    default_label: impl FnOnce() -> Option<String>,
) -> bool {
    let target = eval_targets().get(id).cloned();
    match target {
        Some(EvalTarget::Window(label)) => label == caller,
        Some(EvalTarget::DefaultWindow) => default_label().as_deref() == Some(caller),
        None => false,
    }
}

impl Drop for PendingSlot {
    fn drop(&mut self) {
        eval_targets().remove(&self.id);
        // The map's lock is async and only held for map operations, so it is almost always
        // free; when it is not, finish the removal on the runtime (or block, outside one).
        if let Ok(mut map) = self.map.try_lock() {
            map.remove(&self.id);
            return;
        }
        let map = Arc::clone(&self.map);
        let id = std::mem::take(&mut self.id);
        match tokio::runtime::Handle::try_current() {
            Ok(rt) => {
                rt.spawn(async move {
                    map.lock().await.remove(&id);
                });
            }
            Err(_) => {
                map.blocking_lock().remove(&id);
            }
        }
    }
}

/// Runtime state shared between the MCP server and all tool handlers.
///
/// Built by the plugin at setup; apps reach it via
/// `app.try_state::<Arc<VictauriState>>()` (see [`register_commands!`]).
/// `#[non_exhaustive]`: new state can be added without a breaking release.
#[non_exhaustive]
pub struct VictauriState {
    /// Ring-buffer event log for IPC calls, state changes, and DOM mutations.
    pub event_log: EventLog,
    /// Registry of all discovered Tauri commands with metadata.
    pub registry: CommandRegistry,
    /// TCP port the MCP server listens on (may differ from configured port if fallback was used).
    pub port: AtomicU16,
    /// Pending JavaScript eval callbacks awaiting webview responses.
    pub pending_evals: PendingCallbacks,
    /// Session recorder for time-travel debugging.
    pub recorder: EventRecorder,
    /// Privacy configuration (tool disabling, command filtering, output redaction).
    pub privacy: privacy::PrivacyConfig,
    /// Timeout for JavaScript eval operations.
    pub eval_timeout: std::time::Duration,
    /// Sends `true` to signal graceful MCP server shutdown.
    pub shutdown_tx: watch::Sender<bool>,
    /// Instant the plugin was initialized, for uptime tracking.
    pub started_at: std::time::Instant,
    /// Total number of MCP tool invocations since startup.
    pub tool_invocations: AtomicU64,
    /// Whether `file:` URLs are allowed in the `navigate` tool's `go_to` action.
    /// Defaults to `false` — only `http` and `https` are permitted unless opted in
    /// via [`VictauriBuilder::allow_file_navigation`].
    pub allow_file_navigation: bool,
    /// Per-command execution timing for Rust-side profiling.
    pub command_timings: introspection::CommandTimings,
    /// Active fault injection rules for chaos engineering.
    pub fault_registry: introspection::FaultRegistry,
    /// Recorded IPC contract baselines for schema drift detection.
    pub contract_store: introspection::ContractStore,
    /// Plugin startup phase timestamps for performance analysis.
    pub startup_timeline: introspection::StartupTimeline,
    /// Captured Tauri event bus events (from `listen_any`).
    pub event_bus: introspection::EventBusMonitor,
    /// Tracker for Victauri's own spawned async tasks.
    pub task_tracker: introspection::TaskTracker,
    /// Set to `true` when any webview's JS bridge sends its ready signal.
    pub bridge_ready: AtomicBool,
    /// Notifies waiters when the JS bridge ready signal arrives.
    pub bridge_notify: tokio::sync::Notify,
    /// Screencast state for the `trace` tool (background frame capture buffer).
    pub screencast: Arc<screencast::Screencast>,
    /// Extra absolute directories searched by `query_db` / `introspect db_health`
    /// in addition to the OS app directories. Lets Victauri reach databases an
    /// app stores outside the Tauri app-data dir (e.g. a project or working
    /// directory). Opt in via [`VictauriBuilder::db_search_paths`]. Absolute
    /// `query_db` paths are permitted only when they resolve within one of these
    /// roots (or an app directory).
    pub db_search_paths: Vec<std::path::PathBuf>,
    /// Application-defined state probes surfaced via the `app_state` tool.
    /// Registered through [`VictauriBuilder::probe`].
    pub probes: introspection::AppStateProbes,
    /// Shared per-window watermarks for draining JS events into a recording.
    pub(crate) drain_watermarks: introspection::DrainWatermarks,
    /// Per-window page-load generations (bumped by each bridge ready signal).
    pub(crate) page_loads: introspection::PageLoads,
}

impl VictauriState {
    /// A standalone state with test-friendly defaults, for driving the MCP
    /// router (`mcp::build_app*`) without a Tauri runtime.
    ///
    /// Defaults: 1000-event log and recorder, port 0, default (full-control)
    /// privacy, 30 s eval timeout, bridge already marked ready, no db search
    /// paths or probes. All fields are `pub`, so adjust any of them on the
    /// returned value before wrapping it in an `Arc`.
    ///
    /// Not part of the supported API — it exists so out-of-crate tests can build
    /// the (`#[non_exhaustive]`) state.
    #[doc(hidden)]
    #[must_use]
    pub fn for_tests() -> Self {
        Self {
            event_log: EventLog::new(1000),
            registry: CommandRegistry::new(),
            port: AtomicU16::new(0),
            pending_evals: Arc::new(Mutex::new(HashMap::new())),
            recorder: EventRecorder::new(1000),
            privacy: privacy::PrivacyConfig::default(),
            eval_timeout: std::time::Duration::from_secs(30),
            shutdown_tx: watch::channel(false).0,
            started_at: std::time::Instant::now(),
            tool_invocations: AtomicU64::new(0),
            allow_file_navigation: false,
            command_timings: introspection::CommandTimings::new(),
            fault_registry: introspection::FaultRegistry::new(),
            contract_store: introspection::ContractStore::new(),
            startup_timeline: introspection::StartupTimeline::new(),
            event_bus: introspection::EventBusMonitor::default(),
            task_tracker: introspection::TaskTracker::new(),
            bridge_ready: AtomicBool::new(true),
            bridge_notify: tokio::sync::Notify::new(),
            screencast: Arc::new(screencast::Screencast::default()),
            db_search_paths: Vec::new(),
            probes: introspection::AppStateProbes::default(),
            drain_watermarks: introspection::DrainWatermarks::default(),
            page_loads: introspection::PageLoads::default(),
        }
    }
}

/// Builder for configuring the Victauri plugin before adding it to a Tauri app.
///
/// Supports port selection, authentication, privacy controls, output redaction,
/// and capacity tuning. All settings have sensible defaults and can be overridden
/// via environment variables.
///
/// **Authentication is enabled by default** with an auto-generated token written to
/// the per-user discovery directory (`<root>/<pid>/token`; the root is `%TEMP%\victauri` on
/// Windows, and on Unix `$XDG_RUNTIME_DIR/victauri`, `<temp>/victauri-<uid>` or
/// `~/.local/state/victauri`). MCP clients that read
/// this file get seamless access. Set `VICTAURI_AUTH_TOKEN` for a fixed token, or
/// call [`auth_disabled()`](VictauriBuilder::auth_disabled) to opt out for local-only
/// single-user development.
pub struct VictauriBuilder {
    port: Option<u16>,
    event_capacity: usize,
    recorder_capacity: usize,
    eval_timeout: std::time::Duration,
    auth_token: Option<String>,
    auth_explicitly_enabled: bool,
    auth_explicitly_disabled: bool,
    disabled_tools: Vec<String>,
    command_allowlist: Option<Vec<String>>,
    command_blocklist: Vec<String>,
    storage_key_blocklist: Vec<String>,
    redaction_patterns: Vec<String>,
    redaction_enabled: bool,
    strict_privacy: bool,
    privacy_profile: Option<privacy::PrivacyProfile>,
    bridge_capacities: js_bridge::BridgeCapacities,
    on_ready: Option<Box<dyn FnOnce(u16) + Send + 'static>>,
    commands: Vec<victauri_core::CommandInfo>,
    allow_file_navigation: bool,
    listen_events: Vec<String>,
    db_search_paths: Vec<std::path::PathBuf>,
    probes: Vec<(String, std::sync::Arc<introspection::ProbeFn>)>,
}

impl Default for VictauriBuilder {
    fn default() -> Self {
        Self {
            port: None,
            event_capacity: DEFAULT_EVENT_CAPACITY,
            recorder_capacity: DEFAULT_RECORDER_CAPACITY,
            eval_timeout: DEFAULT_EVAL_TIMEOUT,
            auth_token: None,
            auth_explicitly_enabled: false,
            auth_explicitly_disabled: false,
            disabled_tools: Vec::new(),
            command_allowlist: None,
            command_blocklist: Vec::new(),
            storage_key_blocklist: Vec::new(),
            redaction_patterns: Vec::new(),
            redaction_enabled: false,
            strict_privacy: false,
            privacy_profile: None,
            bridge_capacities: js_bridge::BridgeCapacities::default(),
            on_ready: None,
            commands: Vec::new(),
            allow_file_navigation: false,
            listen_events: Vec::new(),
            db_search_paths: Vec::new(),
            probes: Vec::new(),
        }
    }
}

impl VictauriBuilder {
    /// Create a new builder with default settings.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Set the TCP port for the MCP server (default: 7373, env: `VICTAURI_PORT`).
    #[must_use]
    pub fn port(mut self, port: u16) -> Self {
        self.port = Some(port);
        self
    }

    /// Set the maximum number of events in the ring-buffer log (default: 10,000).
    #[must_use]
    pub fn event_capacity(mut self, capacity: usize) -> Self {
        self.event_capacity = capacity;
        self
    }

    /// Set the maximum events kept during session recording (default: 50,000).
    #[must_use]
    pub fn recorder_capacity(mut self, capacity: usize) -> Self {
        self.recorder_capacity = capacity;
        self
    }

    /// Set the timeout for JavaScript eval operations (default: 30s, env: `VICTAURI_EVAL_TIMEOUT`).
    #[must_use]
    pub fn eval_timeout(mut self, timeout: std::time::Duration) -> Self {
        self.eval_timeout = timeout;
        self
    }

    /// Set an explicit auth token for the MCP server (env: `VICTAURI_AUTH_TOKEN`).
    ///
    /// Setting a token implicitly enables authentication.
    #[must_use]
    pub fn auth_token(mut self, token: impl Into<String>) -> Self {
        self.auth_token = Some(token.into());
        self
    }

    /// Explicitly enable authentication with an auto-generated `UUID` v4 token.
    ///
    /// **Authentication is already enabled by default** (see [`Self::auth_disabled`]),
    /// so this call is redundant in normal use and is kept for explicitness and
    /// backward compatibility. The token is never logged; it is written only to
    /// the per-user discovery directory (`<root>/<pid>/token`; the root is `%TEMP%\victauri` on
    /// Windows, and on Unix `$XDG_RUNTIME_DIR/victauri`, `<temp>/victauri-<uid>` or
    /// `~/.local/state/victauri`)
    /// for client auto-discovery.
    #[must_use]
    pub fn auth_enabled(mut self) -> Self {
        self.auth_explicitly_enabled = true;
        self
    }

    /// Generate a random `UUID` v4 auth token (alias for [`auth_enabled`](Self::auth_enabled)).
    #[must_use]
    pub fn generate_auth_token(mut self) -> Self {
        self.auth_explicitly_enabled = true;
        self
    }

    /// Disable authentication entirely.
    ///
    /// By default, Victauri auto-generates a Bearer token and writes it to the
    /// discovery directory. Call this method to opt out of authentication for
    /// single-user local development where convenience outweighs the risk.
    ///
    /// **Warning:** Without auth, any process on localhost can invoke all MCP
    /// tools including `eval_js` and `invoke_command`. Only disable auth on
    /// machines where you trust every running process.
    #[must_use]
    pub fn auth_disabled(mut self) -> Self {
        self.auth_explicitly_disabled = true;
        self
    }

    /// Disable specific MCP tools by name (e.g., `["eval_js", "screenshot"]`).
    ///
    /// Accepts a bare tool name (disables every action of a compound tool) or a single
    /// action as `tool.action` (e.g. `"window.manage"`, `"inspect.get_styles"`). A name that
    /// matches no tool or action disables nothing, so it is logged as a warning.
    #[must_use]
    pub fn disable_tools(mut self, tools: &[&str]) -> Self {
        for unknown in mcp::authz::unknown_names(tools.iter().copied()) {
            tracing::warn!(
                name = unknown,
                "disable_tools: {unknown:?} is not a Victauri tool, `tool.action`, or capability \
                 name, so it disables nothing (check the spelling against the tool list)"
            );
        }
        self.disabled_tools = tools.iter().map(std::string::ToString::to_string).collect();
        self
    }

    /// Only allow these Tauri commands to be invoked via MCP (positive allowlist).
    #[must_use]
    pub fn command_allowlist(mut self, commands: &[&str]) -> Self {
        self.command_allowlist = Some(
            commands
                .iter()
                .map(std::string::ToString::to_string)
                .collect(),
        );
        self
    }

    /// Block specific Tauri commands from being invoked via MCP.
    #[must_use]
    pub fn command_blocklist(mut self, commands: &[&str]) -> Self {
        self.command_blocklist = commands
            .iter()
            .map(std::string::ToString::to_string)
            .collect();
        self
    }

    /// Block `storage.set` from writing these `localStorage`/`sessionStorage` keys.
    /// Use it to protect keys your app trusts for auth/role/tier/feature decisions
    /// so an agent cannot escalate privilege by poisoning them (audit #33). Default
    /// is empty (no keys blocked), preserving existing behaviour.
    #[must_use]
    pub fn storage_key_blocklist(mut self, keys: &[&str]) -> Self {
        self.storage_key_blocklist = keys.iter().map(std::string::ToString::to_string).collect();
        self
    }

    /// Add a regex pattern for output redaction (e.g., `r"SECRET_\w+"`).
    #[must_use]
    pub fn add_redaction_pattern(mut self, pattern: impl Into<String>) -> Self {
        self.redaction_patterns.push(pattern.into());
        self
    }

    /// Enable output redaction with built-in patterns (API keys, emails, tokens).
    #[must_use]
    pub fn enable_redaction(mut self) -> Self {
        self.redaction_enabled = true;
        self
    }

    /// Enable strict privacy mode (equivalent to [`PrivacyProfile::Observe`]).
    ///
    /// Disables all mutation tools (`eval_js`, screenshot, interactions, input,
    /// storage writes, navigation, CSS injection) and enables output redaction.
    ///
    /// Prefer [`privacy_profile()`](Self::privacy_profile) for finer control.
    #[must_use]
    pub fn strict_privacy_mode(mut self) -> Self {
        self.strict_privacy = true;
        self.privacy_profile = Some(privacy::PrivacyProfile::Observe);
        self
    }

    /// Set the privacy profile tier.
    ///
    /// - [`Observe`](privacy::PrivacyProfile::Observe) — read-only (snapshots, logs, registry)
    /// - [`Test`](privacy::PrivacyProfile::Test) — observe + interactions + input + storage writes + recording
    /// - [`FullControl`](privacy::PrivacyProfile::FullControl) — everything (default)
    ///
    /// Profiles automatically enable redaction for `Observe` and `Test`.
    /// Use [`disable_tools()`](Self::disable_tools) to apply overrides on top of a profile.
    #[must_use]
    pub fn privacy_profile(mut self, profile: privacy::PrivacyProfile) -> Self {
        self.privacy_profile = Some(profile);
        if matches!(
            profile,
            privacy::PrivacyProfile::Observe | privacy::PrivacyProfile::Test
        ) {
            self.redaction_enabled = true;
        }
        self
    }

    /// Set the maximum console log entries kept in the JS bridge (default: 1000).
    #[must_use]
    pub fn console_log_capacity(mut self, capacity: usize) -> Self {
        self.bridge_capacities.console_logs = capacity;
        self
    }

    /// Set the maximum network log entries kept in the JS bridge (default: 1000).
    #[must_use]
    pub fn network_log_capacity(mut self, capacity: usize) -> Self {
        self.bridge_capacities.network_log = capacity;
        self
    }

    /// Set the maximum navigation log entries kept in the JS bridge (default: 200).
    #[must_use]
    pub fn navigation_log_capacity(mut self, capacity: usize) -> Self {
        self.bridge_capacities.navigation_log = capacity;
        self
    }

    /// Pre-register command schemas so `get_registry`, `resolve_command`, and
    /// `detect_ghost_commands` return real results from the moment the server starts.
    ///
    /// Pass the `__schema()` functions generated by `#[inspectable]`.
    ///
    /// ```rust,ignore
    /// VictauriBuilder::new()
    ///     .commands(&[
    ///         greet__schema(),
    ///         increment__schema(),
    ///         add_todo__schema(),
    ///     ])
    ///     .build()
    /// ```
    #[must_use]
    pub fn commands(mut self, schemas: &[victauri_core::CommandInfo]) -> Self {
        self.commands = schemas.to_vec();
        self
    }

    /// Register command names without full schemas.
    ///
    /// Use this when your commands are decorated with `#[tauri::command]` but not
    /// `#[inspectable]`. Ghost detection will recognize these commands as registered,
    /// eliminating false positives.
    ///
    /// ```rust,ignore
    /// VictauriBuilder::new()
    ///     .register_command_names(&[
    ///         "get_settings",
    ///         "save_settings",
    ///         "run_analysis",
    ///     ])
    ///     .build()
    /// ```
    #[must_use]
    pub fn register_command_names(mut self, names: &[&str]) -> Self {
        self.commands
            .extend(names.iter().map(|n| victauri_core::CommandInfo::new(*n)));
        self
    }

    /// Auto-discover all `#[inspectable]` commands in the binary.
    ///
    /// Uses `inventory` to collect every command marked with `#[inspectable]`
    /// at link time — no manual listing required. This replaces both
    /// `.commands(&[...])` and `register_commands!()`.
    ///
    /// ```rust,ignore
    /// tauri::Builder::default()
    ///     .plugin(
    ///         VictauriBuilder::new()
    ///             .auto_discover()
    ///             .build()
    ///             .unwrap(),
    ///     )
    /// ```
    #[must_use]
    pub fn auto_discover(mut self) -> Self {
        self.commands
            .extend(victauri_core::auto_discovered_commands());
        self
    }

    /// Register custom Tauri event names to capture in the event bus.
    ///
    /// Window lifecycle events (focus, blur, close, resize, move, theme change) are
    /// captured automatically. Use this for app-specific events emitted via `app.emit()`.
    ///
    /// ```rust,ignore
    /// VictauriBuilder::new()
    ///     .listen_events(&["notification-added", "settings-changed", "sync-complete"])
    ///     .build()
    /// ```
    #[must_use]
    pub fn listen_events(mut self, events: &[&str]) -> Self {
        self.listen_events = events
            .iter()
            .map(std::string::ToString::to_string)
            .collect();
        self
    }

    /// Allow `file:` URLs in the `navigate` tool's `go_to` action.
    ///
    /// By default, only `http` and `https` schemes are permitted. Calling this
    /// method opts in to `file:` navigation, which grants the MCP client access
    /// to local filesystem paths via the webview.
    ///
    /// **Warning:** Enabling this in untrusted environments exposes local files
    /// to any process that can reach the MCP server.
    #[must_use]
    pub fn allow_file_navigation(mut self) -> Self {
        self.allow_file_navigation = true;
        self
    }

    /// Add extra directories for `query_db` and `introspect db_health` to search
    /// for `SQLite` databases, beyond the OS app directories.
    ///
    /// Many apps store their database outside the Tauri app-data directory (in a
    /// project/working directory, a user-chosen location, or a configured path).
    /// By default Victauri only searches the OS app directories, so those
    /// databases are unreachable. Registering their containing directory here
    /// makes them discoverable by relative name and permits absolute `query_db`
    /// paths that resolve within these roots.
    ///
    /// Access remains read-only and path-traversal-guarded. Paths are added
    /// as-is; relative paths are resolved against the process working directory.
    #[must_use]
    pub fn db_search_paths<I, P>(mut self, paths: I) -> Self
    where
        I: IntoIterator<Item = P>,
        P: Into<std::path::PathBuf>,
    {
        self.db_search_paths
            .extend(paths.into_iter().map(Into::into));
        self
    }

    /// Register an application state probe surfaced through the `app_state` tool.
    ///
    /// A probe is a named closure returning a JSON snapshot of domain-specific
    /// backend state. It gives an agent first-class, discoverable access to state
    /// that would otherwise only be reachable by `query_db` + grepping logs —
    /// e.g. a scoring pipeline's version and queue depth, a cache's hit rate, or
    /// a scheduler's next-run time. The closure runs in the Rust process with no
    /// IPC round-trip, so it can read backend state the frontend never sees.
    ///
    /// The idiomatic pattern is to build your shared state as an `Arc` first, then
    /// clone it into both Tauri's `.manage()` and the probe:
    ///
    /// ```no_run
    /// # use std::sync::Arc;
    /// # use serde_json::json;
    /// # struct Scoring; impl Scoring { fn version(&self) -> u32 { 5 } fn stale(&self) -> u64 { 0 } }
    /// let scoring = Arc::new(Scoring);
    /// let probe_state = Arc::clone(&scoring);
    /// let builder = victauri_plugin::VictauriBuilder::new().probe("scoring", move || {
    ///     json!({ "pipeline_version": probe_state.version(), "stale_items": probe_state.stale() })
    /// });
    /// # let _ = builder;
    /// ```
    ///
    /// # Threading
    ///
    /// The closure runs on tokio's **blocking pool** (under a deadline, with panics isolated),
    /// never on the Tauri main thread. It must therefore not capture, clone or drop Tauri
    /// handles (`AppHandle`, `Window`, `Webview`, `WebviewWindow`, …) nor call
    /// `get_webview_window` / `webview_windows`: on Linux every Tauri handle carries a
    /// non-atomic `Rc` owned by the main thread (tao's window set), and touching it from another
    /// thread corrupts the host's heap. Read your own `Send + Sync` state (an `Arc`, a lock, an
    /// atomic) instead, as above.
    #[must_use]
    pub fn probe<F>(mut self, name: impl Into<String>, probe: F) -> Self
    where
        F: Fn() -> serde_json::Value + Send + Sync + 'static,
    {
        self.probes.push((name.into(), std::sync::Arc::new(probe)));
        self
    }

    /// Register a callback invoked once the MCP server is listening.
    /// The callback receives the port number.
    ///
    /// # Threading
    ///
    /// The callback runs on a **tokio worker thread** (Tauri's async runtime), not on the main
    /// thread, and blocks that worker while it runs — keep it short. Like a
    /// [`probe`](Self::probe), it must not capture, clone or drop Tauri handles nor call
    /// `get_webview_window` / `webview_windows` (on Linux that races the main thread's
    /// non-atomic `Rc` and corrupts the heap) — moving a handle into the callback means it is
    /// dropped on the worker. To act on the app, signal your own main-thread code instead (a
    /// channel, an atomic, or state it reads).
    #[must_use]
    pub fn on_ready(mut self, f: impl FnOnce(u16) + Send + 'static) -> Self {
        self.on_ready = Some(Box::new(f));
        self
    }

    fn resolve_port(&self) -> u16 {
        self.port
            .or_else(|| std::env::var("VICTAURI_PORT").ok()?.parse().ok())
            .unwrap_or(DEFAULT_PORT)
    }

    fn resolve_auth_token(&self) -> Option<String> {
        if self.auth_explicitly_disabled {
            return None;
        }
        // An EMPTY/whitespace configured token or env var is treated as "not configured" and
        // falls through to a freshly generated token — it must NOT disable auth. The contract is
        // "auth is on by default unless `auth_disabled()`"; a botched `VICTAURI_AUTH_TOKEN=""`
        // (or `.auth_token("")`) previously collapsed to no-auth downstream, a silent fail-open
        // that bypassed that contract without the caller ever invoking `auth_disabled()`.
        if let Some(ref token) = self.auth_token
            && !token.trim().is_empty()
        {
            return Some(token.clone());
        }
        if let Ok(token) = std::env::var("VICTAURI_AUTH_TOKEN")
            && !token.trim().is_empty()
        {
            return Some(token);
        }
        Some(auth::generate_token())
    }

    fn resolve_eval_timeout(&self) -> std::time::Duration {
        std::env::var("VICTAURI_EVAL_TIMEOUT")
            .ok()
            .and_then(|s| s.parse::<u64>().ok())
            .map_or(self.eval_timeout, std::time::Duration::from_secs)
    }

    fn build_privacy_config(&self) -> privacy::PrivacyConfig {
        let profile = self
            .privacy_profile
            .unwrap_or(privacy::PrivacyProfile::FullControl);

        let redaction_enabled = self.redaction_enabled
            || self.strict_privacy
            || matches!(
                profile,
                privacy::PrivacyProfile::Observe | privacy::PrivacyProfile::Test
            );

        privacy::PrivacyConfig {
            profile,
            command_allowlist: self
                .command_allowlist
                .as_ref()
                .map(|v| v.iter().cloned().collect::<HashSet<String>>()),
            command_blocklist: self.command_blocklist.iter().cloned().collect(),
            disabled_tools: self.disabled_tools.iter().cloned().collect(),
            storage_key_blocklist: self.storage_key_blocklist.iter().cloned().collect(),
            redactor: redaction::Redactor::new(&self.redaction_patterns),
            redaction_enabled,
        }
    }

    fn validate(&self) -> Result<(), BuilderError> {
        let port = self.resolve_port();
        if port == 0 {
            return Err(BuilderError::InvalidPort {
                port,
                reason: "port 0 is reserved".to_string(),
            });
        }

        if self.event_capacity == 0 || self.event_capacity > MAX_EVENT_CAPACITY {
            return Err(BuilderError::InvalidEventCapacity {
                capacity: self.event_capacity,
                reason: format!("must be between 1 and {MAX_EVENT_CAPACITY}"),
            });
        }

        if self.recorder_capacity == 0 || self.recorder_capacity > MAX_RECORDER_CAPACITY {
            return Err(BuilderError::InvalidRecorderCapacity {
                capacity: self.recorder_capacity,
                reason: format!("must be between 1 and {MAX_RECORDER_CAPACITY}"),
            });
        }

        let timeout = self.resolve_eval_timeout();
        if timeout.as_secs() == 0 || timeout.as_secs() > MAX_EVAL_TIMEOUT_SECS {
            return Err(BuilderError::InvalidEvalTimeout {
                timeout_secs: timeout.as_secs(),
                reason: format!("must be between 1 and {MAX_EVAL_TIMEOUT_SECS} seconds"),
            });
        }

        Ok(())
    }

    /// Consume the builder and produce a Tauri plugin.
    ///
    /// In release builds this always succeeds. In debug builds the builder configuration is
    /// validated first.
    ///
    /// # Errors
    ///
    /// Returns [`BuilderError`] if the port, event capacity, recorder capacity, or eval
    /// timeout are outside their valid ranges (debug builds only).
    pub fn build<R: Runtime>(self) -> Result<TauriPlugin<R>, BuilderError> {
        #[cfg(not(debug_assertions))]
        {
            Ok(Builder::new("victauri").build())
        }

        #[cfg(debug_assertions)]
        {
            // Hard kill-switch: lets a team force the no-op plugin even in a debug
            // build (e.g. a release profile compiled with `debug-assertions = true`,
            // or a shared environment where the introspection server must never bind).
            if env_truthy("VICTAURI_DISABLE") {
                tracing::info!("Victauri disabled via VICTAURI_DISABLE — returning no-op plugin");
                return Ok(Builder::new("victauri").build());
            }

            self.validate()?;

            let port = self.resolve_port();
            let event_capacity = self.event_capacity;
            let recorder_capacity = self.recorder_capacity;
            let eval_timeout = self.resolve_eval_timeout();
            let auth_token = self.resolve_auth_token();
            let privacy_config = self.build_privacy_config();
            let allow_file_navigation = self.allow_file_navigation;
            let db_search_paths = self.db_search_paths;
            let on_ready = self.on_ready;
            let commands = self.commands;
            let listen_events = self.listen_events;
            let probes = self.probes;
            let js_init = js_bridge::init_script(&self.bridge_capacities);

            Ok(Builder::new("victauri")
                .setup(move |app, _api| {
                    // Record the main (UI) thread so the bridge can run main-thread callers
                    // inline instead of deadlocking on its lock, and give the bridge a handle
                    // owned by that thread (see `bridge::on_main`). Tauri runs setup there —
                    // unless the app registered this plugin at runtime from a background thread
                    // (`AppHandle::plugin`); then the adoption is posted to the main thread.
                    match bridge::adopt_main_thread(app) {
                        Ok(bridge::MainThreadAdoption::Inline) => {}
                        Ok(bridge::MainThreadAdoption::Posted) => tracing::warn!(
                            "Victauri: plugin setup ran off the main thread (registered at \
                             runtime from a background thread?); the main-thread state is being \
                             installed on the main thread — webview/window tools called before \
                             it is will fail with \"not installed\""
                        ),
                        Err(e) => tracing::error!(
                            "Victauri: could not reach the main thread to install its state \
                             ({e}); webview and window tools will fail with \"not installed\""
                        ),
                    }
                    let startup_timeline = introspection::StartupTimeline::new();
                    let event_log = EventLog::new(event_capacity);
                    startup_timeline.mark("event_log_created");
                    let registry = CommandRegistry::new();
                    startup_timeline.mark("registry_created");
                    let (shutdown_tx, shutdown_rx) = watch::channel(false);

                    // Resolve configured db search paths against multiple anchors so a
                    // CWD-relative path (e.g. 4DA's "../data", relative to src-tauri/) is
                    // found regardless of the launch CWD — the binary usually runs from
                    // target/debug/, so CWD-only resolution silently misses the database.
                    let db_search_paths = resolve_db_search_paths(&db_search_paths);

                    let state = Arc::new(VictauriState {
                        event_log,
                        registry,
                        port: AtomicU16::new(port),
                        pending_evals: Arc::new(Mutex::new(HashMap::new())),
                        recorder: EventRecorder::new(recorder_capacity),
                        privacy: privacy_config,
                        eval_timeout,
                        shutdown_tx,
                        started_at: std::time::Instant::now(),
                        tool_invocations: AtomicU64::new(0),
                        allow_file_navigation,
                        command_timings: introspection::CommandTimings::new(),
                        fault_registry: introspection::FaultRegistry::new(),
                        contract_store: introspection::ContractStore::new(),
                        startup_timeline,
                        event_bus: introspection::EventBusMonitor::default(),
                        task_tracker: introspection::TaskTracker::new(),
                        bridge_ready: AtomicBool::new(false),
                        bridge_notify: tokio::sync::Notify::new(),
                        screencast: Arc::new(screencast::Screencast::default()),
                        db_search_paths,
                        probes: introspection::AppStateProbes::default(),
                        drain_watermarks: introspection::DrainWatermarks::default(),
                        page_loads: introspection::PageLoads::default(),
                    });
                    state.startup_timeline.mark("state_created");

                    for (name, probe) in probes {
                        state.probes.register(name, probe);
                    }

                    app.manage(state.clone());

                    for cmd in commands {
                        state.registry.register(cmd);
                    }
                    state.startup_timeline.mark("commands_registered");

                    // Register listeners for custom event names specified via builder.
                    for event_name in &listen_events {
                        let bus = state.event_bus.clone();
                        let name = event_name.clone();
                        app.listen_any(event_name.clone(), move |event| {
                            let payload =
                                serde_json::from_str::<serde_json::Value>(event.payload())
                                    .map_or_else(
                                        |_| event.payload().to_string(),
                                        |v| v.to_string(),
                                    );
                            bus.push(introspection::CapturedTauriEvent {
                                name: name.clone(),
                                payload,
                                timestamp: chrono::Utc::now()
                                    .to_rfc3339_opts(chrono::SecondsFormat::Millis, true),
                            });
                        });
                    }
                    state
                        .startup_timeline
                        .mark("event_bus_listeners_registered");

                    if auth_token.is_some() {
                        // Nothing about the token itself: even a prefix and length narrow a
                        // guess, and logs travel further than the owner-only discovery file.
                        tracing::info!(
                            "Victauri MCP server auth enabled — clients read the token from \
                             the discovery directory"
                        );
                    } else {
                        tracing::warn!(
                            "Victauri MCP server running WITHOUT auth — any localhost process can \
                             access all tools. Use VictauriBuilder::auth_enabled() or set \
                             VICTAURI_AUTH_TOKEN for shared/CI environments."
                        );
                    }

                    state.startup_timeline.mark("server_spawning");
                    let app_handle = app.clone();
                    let ready_state = state.clone();
                    let server_finished = state.task_tracker.track_guarded("mcp_server");
                    let (bound_tx, bound_rx) = tokio::sync::oneshot::channel();
                    tauri::async_runtime::spawn(async move {
                        let _finished = server_finished;
                        match mcp::start_server_reporting_port(
                            app_handle,
                            state,
                            port,
                            auth_token,
                            shutdown_rx,
                            Some(bound_tx),
                        )
                        .await
                        {
                            Ok(()) => {
                                tracing::info!("Victauri MCP server stopped");
                            }
                            Err(e) => {
                                tracing::error!("Victauri MCP server failed: {e}");
                            }
                        }
                    });

                    // The banner and `on_ready` report the port the server actually BOUND. They
                    // used the preferred port, and probing it by connecting could reach another
                    // process squatting on it — or report it after the 5s probe gave up even
                    // though nothing of ours was listening.
                    let ready_finished = ready_state.task_tracker.track_guarded("on_ready_probe");
                    tauri::async_runtime::spawn(async move {
                        let _finished = ready_finished;
                        match tokio::time::timeout(std::time::Duration::from_secs(5), bound_rx)
                            .await
                        {
                            Ok(Ok(Ok(actual_port))) => {
                                emit_security_banner(actual_port);
                                if let Some(cb) = on_ready {
                                    cb(actual_port);
                                }
                            }
                            Ok(Ok(Err(e))) => tracing::warn!(
                                "Victauri: server did not start ({e}); on_ready not called"
                            ),
                            Ok(Err(_)) | Err(_) => tracing::warn!(
                                "Victauri: server did not report a bound port within 5s; \
                                 on_ready not called"
                            ),
                        }
                    });
                    Ok(())
                })
                .on_event(|app, event| {
                    let Some(state) = app.try_state::<Arc<VictauriState>>() else {
                        return;
                    };
                    match event {
                        RunEvent::Exit => {
                            // `send_replace`: the value must flip even with no receiver left
                            // (`send` then leaves it unchanged), since an eval started after
                            // this reads it directly.
                            state.shutdown_tx.send_replace(true);
                            tracing::info!("Victauri shutdown signal sent");
                        }
                        RunEvent::ExitRequested { .. } => {
                            state.event_bus.push(introspection::CapturedTauriEvent {
                                name: "tauri://exit-requested".to_string(),
                                payload: String::new(),
                                timestamp: chrono::Utc::now()
                                    .to_rfc3339_opts(chrono::SecondsFormat::Millis, true),
                            });
                        }
                        RunEvent::WindowEvent {
                            label,
                            event: win_event,
                            ..
                        } => {
                            let (name, payload) = format_window_event(label, win_event);
                            state.event_bus.push(introspection::CapturedTauriEvent {
                                name,
                                payload,
                                timestamp: chrono::Utc::now()
                                    .to_rfc3339_opts(chrono::SecondsFormat::Millis, true),
                            });
                        }
                        _ => {}
                    }
                })
                .js_init_script(js_init)
                .invoke_handler(tauri::generate_handler![
                    tools::victauri_eval_js,
                    tools::victauri_eval_callback,
                    tools::victauri_get_window_state,
                    tools::victauri_list_windows,
                    tools::victauri_get_ipc_log,
                    tools::victauri_get_registry,
                    tools::victauri_get_memory_stats,
                    tools::victauri_dom_snapshot,
                    tools::victauri_verify_state,
                    tools::victauri_detect_ghost_commands,
                    tools::victauri_check_ipc_integrity,
                ])
                .build())
        }
    }
}

#[cfg(debug_assertions)]
fn format_window_event(label: &str, event: &tauri::WindowEvent) -> (String, String) {
    match event {
        tauri::WindowEvent::Resized(size) => (
            format!("window:{label}:resized"),
            serde_json::json!({"width": size.width, "height": size.height}).to_string(),
        ),
        tauri::WindowEvent::Moved(pos) => (
            format!("window:{label}:moved"),
            serde_json::json!({"x": pos.x, "y": pos.y}).to_string(),
        ),
        tauri::WindowEvent::CloseRequested { .. } => {
            (format!("window:{label}:close-requested"), String::new())
        }
        tauri::WindowEvent::Destroyed => (format!("window:{label}:destroyed"), String::new()),
        tauri::WindowEvent::Focused(focused) => (
            format!("window:{label}:focused"),
            serde_json::json!({"focused": focused}).to_string(),
        ),
        tauri::WindowEvent::ScaleFactorChanged { scale_factor, .. } => (
            format!("window:{label}:scale-factor-changed"),
            serde_json::json!({"scale_factor": scale_factor}).to_string(),
        ),
        tauri::WindowEvent::ThemeChanged(theme) => (
            format!("window:{label}:theme-changed"),
            serde_json::json!({"theme": format!("{theme:?}")}).to_string(),
        ),
        tauri::WindowEvent::DragDrop(drag_event) => (
            format!("window:{label}:drag-drop"),
            format!("{drag_event:?}"),
        ),
        _ => (format!("window:{label}:other"), format!("{event:?}")),
    }
}

/// Returns `true` if the named environment variable is set to a truthy value
/// (`1`, `true`, `yes`, or `on`, case-insensitive, surrounding whitespace ignored).
/// Unset, empty, or any other value is `false`.
#[cfg(debug_assertions)]
fn env_truthy(name: &str) -> bool {
    std::env::var(name).is_ok_and(|v| {
        matches!(
            v.trim().to_ascii_lowercase().as_str(),
            "1" | "true" | "yes" | "on"
        )
    })
}

/// Emits an unmissable startup banner whenever the introspection server activates.
///
/// Victauri is a debug-only tool that exposes JS eval, IPC, the filesystem, and
/// `SQLite` over localhost. Logging this loudly on every start guarantees it can
/// never run *silently* — most importantly catching the dangerous case of a
/// release build accidentally compiled with `debug-assertions = true`, where the
/// `#[cfg(debug_assertions)]` gate would otherwise let the full server bind with
/// no visible signal.
#[cfg(debug_assertions)]
fn emit_security_banner(port: u16) {
    tracing::warn!(
        "┌─ VICTAURI INTROSPECTION SERVER ACTIVE ─────────────────────────────\n\
         │ Listening on http://127.0.0.1:{port} — exposes JS eval, IPC, the\n\
         │ filesystem, and SQLite to local clients. DEBUG-ONLY developer tool;\n\
         │ it must never reach end users.\n\
         │ Seeing this in a shipped/release build means your release profile has\n\
         │ `debug-assertions = true`. Turn that off, or hard-disable Victauri\n\
         │ with the VICTAURI_DISABLE=1 environment variable.\n\
         └────────────────────────────────────────────────────────────────────"
    );
}

/// Initialize the Victauri plugin with default settings (port 7373 or `VICTAURI_PORT` env var).
///
/// In debug builds: starts the embedded MCP server with **authentication enabled**
/// (auto-generated token written to the per-user discovery directory (`<root>/<pid>/token`; the root is `%TEMP%\victauri` on
/// Windows, and on Unix `$XDG_RUNTIME_DIR/victauri`, `<temp>/victauri-<uid>` or
/// `~/.local/state/victauri`)), injects the JS
/// bridge, and registers all Tauri command handlers.
///
/// In release builds: returns a no-op plugin. The MCP server, JS bridge, and
/// all introspection tools are completely stripped — zero overhead, zero attack surface.
///
/// Setting the `VICTAURI_DISABLE=1` environment variable forces the no-op plugin
/// even in a debug build — a hard kill-switch for shared environments or a release
/// profile compiled with `debug-assertions = true`. When the server does activate
/// Resolve configured `db_search_paths` against multiple stable anchors so a
/// relative path is found regardless of the launch CWD.
///
/// Real apps register CWD-relative paths — e.g. 4DA's `../data` is relative to
/// `src-tauri/` — but the binary usually runs from `target/debug/` or a bundle,
/// so resolving only against the current directory silently misses the database
/// (the single most valuable backend surface). We resolve each relative path
/// against the CWD **and every ancestor of the executable**, keeping each
/// candidate that exists as a directory. Absolute paths pass through. The result
/// is deduped canonical directories.
fn resolve_db_search_paths(configured: &[std::path::PathBuf]) -> Vec<std::path::PathBuf> {
    resolve_db_search_paths_against(configured, &db_search_anchors())
}

/// Collect stable anchor directories for resolving relative db search paths: the
/// CWD plus every ancestor of the executable.
fn db_search_anchors() -> Vec<std::path::PathBuf> {
    use std::path::PathBuf;
    let mut anchors: Vec<PathBuf> = Vec::new();
    if let Ok(cwd) = std::env::current_dir() {
        anchors.push(cwd);
    }
    if let Ok(exe) = std::env::current_exe() {
        let mut dir = exe.parent().map(PathBuf::from);
        // Walk up the executable's ancestors (target/debug -> target -> src-tauri
        // -> project root -> ...), so a path relative to any of them resolves.
        for _ in 0..8 {
            match dir {
                Some(d) => {
                    anchors.push(d.clone());
                    dir = d.parent().map(PathBuf::from);
                }
                None => break,
            }
        }
    }
    anchors
}

/// Pure core (testable): resolve each configured path against the given anchors,
/// keeping every candidate that exists as a directory. Absolute paths pass
/// through. Result is deduped canonical directories.
fn resolve_db_search_paths_against(
    configured: &[std::path::PathBuf],
    anchors: &[std::path::PathBuf],
) -> Vec<std::path::PathBuf> {
    let mut out: Vec<std::path::PathBuf> = Vec::new();
    for p in configured {
        if p.is_absolute() {
            out.push(p.canonicalize().unwrap_or_else(|_| p.clone()));
        } else {
            for a in anchors {
                if let Ok(c) = a.join(p).canonicalize()
                    && c.is_dir()
                {
                    out.push(c);
                }
            }
        }
    }
    out.sort();
    out.dedup();
    out
}

/// it always logs a prominent startup banner, so it can never run silently.
///
/// For custom configuration, use `VictauriBuilder::new().port(8080).build()`.
///
/// # Panics
///
/// Panics if the default builder configuration is invalid (this is a bug).
#[must_use]
pub fn init<R: Runtime>() -> TauriPlugin<R> {
    VictauriBuilder::new()
        .build()
        .expect("default Victauri configuration is always valid")
}

/// Initialize the Victauri plugin with auto-discovery of all `#[inspectable]` commands.
///
/// Equivalent to `VictauriBuilder::new().auto_discover().build()` — all commands
/// marked with `#[inspectable]` are registered automatically without manual listing.
///
/// # Panics
///
/// Panics if the default builder configuration is invalid (this is a bug).
#[must_use]
pub fn init_auto_discover<R: Runtime>() -> TauriPlugin<R> {
    VictauriBuilder::new()
        .auto_discover()
        .build()
        .expect("default Victauri configuration is always valid")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn db_search_resolves_relative_path_via_a_non_cwd_anchor() {
        // Reproduces the live-4DA gap: the DB lives under one anchor (e.g. the
        // project dir) via a relative path, but the process CWD is elsewhere
        // (e.g. target/debug). Multi-anchor resolution must still find it.
        use std::path::PathBuf;
        let tmp = tempfile::tempdir().unwrap();
        let project = tmp.path().join("myapp");
        let data = project.join("data");
        std::fs::create_dir_all(&data).unwrap();
        std::fs::write(data.join("app.db"), b"x").unwrap();
        // Simulate the binary running from project/src-tauri/target/debug: the CWD
        // anchor (an unrelated dir) does NOT contain "../data", but the
        // "src-tauri" ancestor does.
        let wrong_cwd = tmp.path().join("elsewhere");
        std::fs::create_dir_all(&wrong_cwd).unwrap();
        let src_tauri = project.join("src-tauri");
        std::fs::create_dir_all(&src_tauri).unwrap();

        let configured = vec![PathBuf::from("../data")]; // 4DA's exact config
        // CWD-only resolution (the old behavior) finds nothing:
        let cwd_only =
            resolve_db_search_paths_against(&configured, std::slice::from_ref(&wrong_cwd));
        assert!(
            cwd_only.is_empty(),
            "CWD-only should miss the db, got {cwd_only:?}"
        );
        // Multi-anchor resolution (CWD + the src-tauri ancestor) finds it:
        let multi = resolve_db_search_paths_against(&configured, &[wrong_cwd, src_tauri]);
        let want = data.canonicalize().unwrap();
        assert!(
            multi.contains(&want),
            "multi-anchor should resolve ../data to {want:?}, got {multi:?}"
        );
    }

    #[test]
    fn db_search_passes_absolute_and_dedups() {
        use std::path::PathBuf;
        let tmp = tempfile::tempdir().unwrap();
        let data = tmp.path().join("data");
        std::fs::create_dir_all(&data).unwrap();
        let abs = data.canonicalize().unwrap();
        // Same dir reachable two ways must dedupe to one canonical entry.
        let out = resolve_db_search_paths_against(
            &[abs.clone(), PathBuf::from("data")],
            &[tmp.path().to_path_buf(), tmp.path().to_path_buf()],
        );
        assert_eq!(
            out.iter().filter(|p| **p == abs).count(),
            1,
            "must dedupe: {out:?}"
        );
    }

    #[test]
    fn builder_default_values() {
        let builder = VictauriBuilder::new();
        assert_eq!(builder.event_capacity, DEFAULT_EVENT_CAPACITY);
        assert_eq!(builder.recorder_capacity, DEFAULT_RECORDER_CAPACITY);
        assert!(builder.auth_token.is_none());
        assert!(!builder.auth_explicitly_enabled);
        assert!(!builder.auth_explicitly_disabled);
        let resolved = builder.resolve_auth_token();
        assert!(
            resolved.is_some(),
            "auth should be enabled by default (auto-generated token)"
        );
        assert_eq!(
            resolved.unwrap().len(),
            36,
            "auto-generated token should be UUID v4"
        );
        assert!(builder.disabled_tools.is_empty());
        assert!(builder.command_allowlist.is_none());
        assert!(builder.command_blocklist.is_empty());
        assert!(!builder.redaction_enabled);
        assert!(!builder.strict_privacy);
    }

    #[test]
    fn builder_port_override() {
        let builder = VictauriBuilder::new().port(9090);
        assert_eq!(builder.resolve_port(), 9090);
    }

    #[test]
    #[allow(unsafe_code)]
    fn builder_default_port() {
        let builder = VictauriBuilder::new();
        // SAFETY: test-only — no concurrent env reads in this test binary.
        unsafe { std::env::remove_var("VICTAURI_PORT") };
        assert_eq!(builder.resolve_port(), DEFAULT_PORT);
    }

    #[test]
    fn builder_auth_token_explicit() {
        let builder = VictauriBuilder::new().auth_token("my-secret");
        assert_eq!(builder.resolve_auth_token(), Some("my-secret".to_string()));
    }

    // `env_truthy` is part of the debug-only kill-switch path, so this test can
    // only reference it in debug builds (otherwise `cargo test --release` fails to
    // compile — a config our CI doesn't normally run).
    #[cfg(debug_assertions)]
    #[test]
    #[allow(unsafe_code)]
    fn env_truthy_recognizes_kill_switch_values() {
        // Unique var name so this never races with other env-touching tests.
        let key = "VICTAURI_TEST_KILL_SWITCH";
        // SAFETY: test-only — this var is unique to this test, no concurrent readers.
        unsafe { std::env::remove_var(key) };
        assert!(!env_truthy(key), "unset should be false");

        for v in ["1", "true", "TRUE", " yes ", "On"] {
            // SAFETY: test-only — unique var, no concurrent readers.
            unsafe { std::env::set_var(key, v) };
            assert!(env_truthy(key), "{v:?} should be truthy");
        }
        for v in ["0", "false", "", "nope"] {
            // SAFETY: test-only — unique var, no concurrent readers.
            unsafe { std::env::set_var(key, v) };
            assert!(!env_truthy(key), "{v:?} should be falsy");
        }
        // SAFETY: test-only — restore clean state.
        unsafe { std::env::remove_var(key) };
    }

    #[test]
    fn builder_auth_enabled() {
        let builder = VictauriBuilder::new().auth_enabled();
        assert!(builder.auth_explicitly_enabled);
        let token = builder.resolve_auth_token().unwrap();
        assert_eq!(token.len(), 36, "auto-generated token should be a UUID");
    }

    #[test]
    fn builder_auth_generate_token() {
        let builder = VictauriBuilder::new().generate_auth_token();
        let token = builder.resolve_auth_token().unwrap();
        assert_eq!(token.len(), 36);
    }

    #[test]
    fn builder_auth_disabled_suppresses_default_token() {
        let builder = VictauriBuilder::new().auth_disabled();
        assert!(
            builder.resolve_auth_token().is_none(),
            "auth_disabled must suppress the default auto-generated token (auth is ON by default)"
        );
    }

    #[test]
    fn builder_auth_disabled_returns_none() {
        let builder = VictauriBuilder::new().auth_disabled();
        assert!(
            builder.resolve_auth_token().is_none(),
            "auth_disabled should suppress auto-generated token"
        );
    }

    #[test]
    fn builder_auth_disabled_overrides_explicit_token() {
        let builder = VictauriBuilder::new()
            .auth_token("my-secret")
            .auth_disabled();
        assert!(
            builder.resolve_auth_token().is_none(),
            "auth_disabled should override explicit token"
        );
    }

    #[test]
    fn builder_empty_explicit_token_does_not_disable_auth() {
        // Fail-open guard: an empty/whitespace token must NOT become "no auth"; it falls
        // through to a freshly generated token. Only `auth_disabled()` disables auth.
        for blank in ["", "   ", "\t\n"] {
            let resolved = VictauriBuilder::new()
                .auth_token(blank)
                .resolve_auth_token();
            assert!(
                resolved.as_deref().is_some_and(|t| !t.trim().is_empty()),
                "empty explicit token {blank:?} must resolve to a generated token, not no-auth"
            );
        }
    }

    #[test]
    fn builder_capacities() {
        let builder = VictauriBuilder::new()
            .event_capacity(500)
            .recorder_capacity(2000);
        assert_eq!(builder.event_capacity, 500);
        assert_eq!(builder.recorder_capacity, 2000);
    }

    #[test]
    fn builder_disable_tools() {
        let builder = VictauriBuilder::new().disable_tools(&["eval_js", "screenshot"]);
        assert_eq!(builder.disabled_tools.len(), 2);
        assert!(builder.disabled_tools.contains(&"eval_js".to_string()));
    }

    #[test]
    fn builder_command_allowlist() {
        let builder = VictauriBuilder::new().command_allowlist(&["greet", "increment"]);
        assert!(builder.command_allowlist.is_some());
        assert_eq!(builder.command_allowlist.as_ref().unwrap().len(), 2);
    }

    #[test]
    fn builder_command_blocklist() {
        let builder = VictauriBuilder::new().command_blocklist(&["dangerous_cmd"]);
        assert_eq!(builder.command_blocklist.len(), 1);
    }

    #[test]
    fn builder_redaction() {
        let builder = VictauriBuilder::new()
            .add_redaction_pattern(r"SECRET_\w+")
            .enable_redaction();
        assert!(builder.redaction_enabled);
        assert_eq!(builder.redaction_patterns.len(), 1);
    }

    #[test]
    fn builder_strict_privacy_config() {
        let builder = VictauriBuilder::new().strict_privacy_mode();
        let config = builder.build_privacy_config();
        assert!(config.redaction_enabled);
        assert_eq!(config.profile, crate::privacy::PrivacyProfile::Observe);
        assert!(!config.is_tool_enabled("eval_js"));
        assert!(!config.is_tool_enabled("screenshot"));
        assert!(!config.is_tool_enabled("interact"));
        assert!(config.is_tool_enabled("dom_snapshot"));
    }

    #[test]
    fn builder_normal_privacy_config() {
        let builder = VictauriBuilder::new()
            .command_blocklist(&["secret_cmd"])
            .disable_tools(&["eval_js"]);
        let config = builder.build_privacy_config();
        assert!(config.command_blocklist.contains("secret_cmd"));
        assert!(!config.is_tool_enabled("eval_js"));
        assert!(!config.redaction_enabled);
    }

    #[test]
    fn builder_strict_with_extra_blocklist() {
        let builder = VictauriBuilder::new()
            .strict_privacy_mode()
            .command_blocklist(&["extra_dangerous"]);
        let config = builder.build_privacy_config();
        assert!(config.command_blocklist.contains("extra_dangerous"));
        assert!(!config.is_tool_enabled("eval_js"));
    }

    #[test]
    fn builder_test_profile() {
        let builder = VictauriBuilder::new().privacy_profile(crate::privacy::PrivacyProfile::Test);
        let config = builder.build_privacy_config();
        assert_eq!(config.profile, crate::privacy::PrivacyProfile::Test);
        assert!(config.redaction_enabled);
        assert!(config.is_tool_enabled("interact"));
        assert!(config.is_tool_enabled("fill"));
        assert!(config.is_tool_enabled("recording"));
        assert!(!config.is_tool_enabled("eval_js"));
        assert!(!config.is_tool_enabled("screenshot"));
        // The bare `navigate` tool surfaces (read actions allowed), but the
        // mutating `go_to` action stays FullControl-only.
        assert!(!config.is_tool_enabled("navigate.go_to"));
    }

    #[test]
    fn builder_profile_with_extra_disables() {
        let builder = VictauriBuilder::new()
            .privacy_profile(crate::privacy::PrivacyProfile::Test)
            .disable_tools(&["interact"]);
        let config = builder.build_privacy_config();
        assert!(!config.is_tool_enabled("interact"));
        assert!(config.is_tool_enabled("fill"));
    }

    #[test]
    fn builder_bridge_capacities() {
        let builder = VictauriBuilder::new()
            .console_log_capacity(5000)
            .network_log_capacity(2000)
            .navigation_log_capacity(500);
        assert_eq!(builder.bridge_capacities.console_logs, 5000);
        assert_eq!(builder.bridge_capacities.network_log, 2000);
        assert_eq!(builder.bridge_capacities.navigation_log, 500);
        assert_eq!(builder.bridge_capacities.mutation_log, 500);
        assert_eq!(builder.bridge_capacities.dialog_log, 100);
    }

    #[test]
    fn builder_on_ready_sets_callback() {
        let builder = VictauriBuilder::new().on_ready(|_port| {});
        assert!(builder.on_ready.is_some());
    }

    #[test]
    fn builder_file_navigation_disabled_by_default() {
        let builder = VictauriBuilder::new();
        assert!(
            !builder.allow_file_navigation,
            "file navigation should be disabled by default"
        );
    }

    #[test]
    fn builder_allow_file_navigation() {
        let builder = VictauriBuilder::new().allow_file_navigation();
        assert!(builder.allow_file_navigation);
    }

    #[test]
    fn builder_listen_events() {
        let builder =
            VictauriBuilder::new().listen_events(&["notification-added", "settings-changed"]);
        assert_eq!(builder.listen_events.len(), 2);
        assert!(
            builder
                .listen_events
                .contains(&"notification-added".to_string())
        );
        assert!(
            builder
                .listen_events
                .contains(&"settings-changed".to_string())
        );
    }

    #[test]
    fn builder_listen_events_empty_by_default() {
        let builder = VictauriBuilder::new();
        assert!(builder.listen_events.is_empty());
    }

    #[test]
    fn init_script_contains_custom_capacities() {
        let caps = js_bridge::BridgeCapacities {
            console_logs: 3000,
            mutation_log: 750,
            network_log: 5000,
            navigation_log: 400,
            dialog_log: 250,
            long_tasks: 200,
        };
        let script = js_bridge::init_script(&caps);
        assert!(script.contains("CAP_CONSOLE = 3000"));
        assert!(script.contains("CAP_MUTATION = 750"));
        assert!(script.contains("CAP_NETWORK = 5000"));
        assert!(script.contains("CAP_NAVIGATION = 400"));
        assert!(script.contains("CAP_DIALOG = 250"));
        assert!(script.contains("CAP_LONG_TASKS = 200"));
    }

    #[test]
    fn init_script_default_contains_standard_capacities() {
        let caps = js_bridge::BridgeCapacities::default();
        let script = js_bridge::init_script(&caps);
        assert!(script.contains("CAP_CONSOLE = 1000"));
        assert!(script.contains("CAP_NETWORK = 1000"));
        assert!(script.contains("window.__VICTAURI__"));
    }

    #[test]
    fn builder_validates_defaults() {
        let builder = VictauriBuilder::new();
        assert!(builder.validate().is_ok());
    }

    #[test]
    fn builder_rejects_zero_port() {
        let builder = VictauriBuilder::new().port(0);
        let err = builder.validate().unwrap_err();
        assert!(matches!(err, BuilderError::InvalidPort { port: 0, .. }));
    }

    #[test]
    fn builder_rejects_zero_event_capacity() {
        let builder = VictauriBuilder::new().event_capacity(0);
        let err = builder.validate().unwrap_err();
        assert!(matches!(
            err,
            BuilderError::InvalidEventCapacity { capacity: 0, .. }
        ));
    }

    #[test]
    fn builder_rejects_excessive_event_capacity() {
        let builder = VictauriBuilder::new().event_capacity(2_000_000);
        assert!(builder.validate().is_err());
    }

    #[test]
    fn builder_rejects_zero_recorder_capacity() {
        let builder = VictauriBuilder::new().recorder_capacity(0);
        assert!(builder.validate().is_err());
    }

    #[test]
    fn builder_rejects_zero_eval_timeout() {
        let builder = VictauriBuilder::new().eval_timeout(std::time::Duration::from_secs(0));
        assert!(builder.validate().is_err());
    }

    #[test]
    fn builder_rejects_excessive_eval_timeout() {
        let builder = VictauriBuilder::new().eval_timeout(std::time::Duration::from_secs(600));
        assert!(builder.validate().is_err());
    }

    #[test]
    fn builder_accepts_edge_values() {
        let builder = VictauriBuilder::new()
            .port(1)
            .event_capacity(1)
            .recorder_capacity(1)
            .eval_timeout(std::time::Duration::from_secs(1));
        assert!(builder.validate().is_ok());

        let builder = VictauriBuilder::new()
            .port(65535)
            .event_capacity(MAX_EVENT_CAPACITY)
            .recorder_capacity(MAX_RECORDER_CAPACITY)
            .eval_timeout(std::time::Duration::from_secs(MAX_EVAL_TIMEOUT_SECS));
        assert!(builder.validate().is_ok());
    }
}