victauri_plugin/

lib.rs

#![deny(missing_docs)]
//! 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 `<temp>/victauri/<pid>/token` 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).
#[cfg(feature = "sqlite")]
pub mod database;
pub mod error;
/// JS bridge script generation for webview injection.
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 mod filmstrip;
/// Output redaction for API keys, tokens, emails, and sensitive JSON keys.
pub mod redaction;
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),+ $(,)?) => {{
        let state = $app.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.
pub type PendingCallbacks = Arc<Mutex<HashMap<String, oneshot::Sender<String>>>>;

/// Runtime state shared between the MCP server and all tool handlers.
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>,
}

/// 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 discovery directory (`<temp>/victauri/<pid>/token`). 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>,
}

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(),
        }
    }
}

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 printed to the log on startup and written
    /// to the discovery directory (`<temp>/victauri/<pid>/token`) 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"]`).
    #[must_use]
    pub fn disable_tools(mut self, tools: &[&str]) -> Self {
        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 a callback invoked once the MCP server is listening.
    /// The callback receives the port number.
    #[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;
        }
        if let Some(ref token) = self.auth_token {
            return Some(token.clone());
        }
        if let Ok(token) = std::env::var("VICTAURI_AUTH_TOKEN") {
            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)]
        {
            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 js_init = js_bridge::init_script(&self.bridge_capacities);

            Ok(Builder::new("victauri")
                .setup(move |app, _api| {
                    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);

                    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,
                    });
                    state.startup_timeline.mark("state_created");

                    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 let Some(ref token) = auth_token {
                        let prefix_len = token.len().min(8);
                        let suffix_start = token.len().saturating_sub(4);
                        tracing::info!(
                            "Victauri MCP server auth enabled — token: {}…{}",
                            &token[..prefix_len],
                            &token[suffix_start..]
                        );
                    } 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("mcp_server");
                    tauri::async_runtime::spawn(async move {
                        match mcp::start_server_with_options(
                            app_handle,
                            state,
                            port,
                            auth_token,
                            shutdown_rx,
                        )
                        .await
                        {
                            Ok(()) => {
                                tracing::info!("Victauri MCP server stopped");
                            }
                            Err(e) => {
                                tracing::error!("Victauri MCP server failed: {e}");
                            }
                        }
                        server_finished.store(true, std::sync::atomic::Ordering::Relaxed);
                    });

                    if let Some(cb) = on_ready {
                        let ready_finished = ready_state.task_tracker.track("on_ready_probe");
                        tauri::async_runtime::spawn(async move {
                            for _ in 0..50 {
                                tokio::time::sleep(std::time::Duration::from_millis(100)).await;
                                let actual_port =
                                    ready_state.port.load(std::sync::atomic::Ordering::Relaxed);
                                if tokio::net::TcpStream::connect(format!(
                                    "127.0.0.1:{actual_port}"
                                ))
                                .await
                                .is_ok()
                                {
                                    cb(actual_port);
                                    ready_finished
                                        .store(true, std::sync::atomic::Ordering::Relaxed);
                                    return;
                                }
                            }
                            let actual_port =
                                ready_state.port.load(std::sync::atomic::Ordering::Relaxed);
                            tracing::warn!(
                                "Victauri on_ready: server did not become ready within 5s"
                            );
                            cb(actual_port);
                            ready_finished.store(true, std::sync::atomic::Ordering::Relaxed);
                        });
                    }

                    tracing::info!("Victauri plugin initialized — MCP server on port {port}");
                    Ok(())
                })
                .on_event(|app, event| {
                    let Some(state) = app.try_state::<Arc<VictauriState>>() else {
                        return;
                    };
                    match event {
                        RunEvent::Exit => {
                            let _ = state.shutdown_tx.send(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:?}")),
    }
}

/// 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 `<temp>/victauri/<pid>/token`), 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.
///
/// 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 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()));
    }

    #[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_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"));
        assert!(!config.is_tool_enabled("navigate"));
    }

    #[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());
    }
}