navop/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Navop is a cross-platform desktop application built on GPUI that provides a unified interface for database management, SSH/SFTP, terminal, and AI tools. The project was migrated from OnetCli, so some compatibility-sensitive protocols, persisted identifiers (such as ProviderType::OnetCli and its onet_cli value), upgrade entries, and public environment variables still use the historical onetcli / OnetCli spelling.

Key capabilities:

• Multi-protocol database management (PostgreSQL, MySQL, SQLite, SQL Server, Oracle, ClickHouse)
• Redis and MongoDB views
• SSH terminal and SFTP file management
• Local terminal with multi-tab workflows
• Cloud sync and account system with encrypted key storage
• Built-in AI chat (Navop built-in provider via llm-connector)

Common Commands

# Run the application
cargo run -p main

# Build
cargo build

# Run all tests
cargo test --all

# Run tests for a specific crate
cargo test -p gpui-component
cargo test -p db
cargo test -p one-core

# Run doc tests
cargo test -p gpui-component --doc

# Lint
cargo clippy -- --deny warnings

# Format check
cargo fmt --check

# Unused dependency check
cargo machete

# Run the component gallery/story showcase
cargo run  # (default members include crates/story)

# Run a single example
cargo run --example table

# Performance profiling (macOS)
MTL_HUD_ENABLED=1 cargo run -p main
samply record cargo run -p main

# Install system dependencies (Linux/macOS)
script/bootstrap

# Install system dependencies (Windows PowerShell)
.\script\install-window.ps1

# Release (bump version in the dev → main PR, then tag on main; see .github/RELEASE.md)
script/release-tag.sh vx.y.z

Workspace Structure

The workspace uses an external gpui-component checkout plus main and the Navop application crates. Edition is 2024.

Application Layer

• main/ — Application entry point and main UI. Orchestrates all subsystems: auth, settings, licensing, updates, home page. Entry: main/src/main.rs → NavopApp.

The navop executable is GUI/update-only and does not embed database, SSH, SFTP, or tool business subcommands. A future standalone navop-cli should connect to the running application through Public MCP discovery and its authenticated tool interface instead of linking directly to main or application state.

Core Infrastructure

• crates/core (one-core) — Core logic: connection management, cloud sync, AI integration, configuration, encryption (AES-GCM, Ed25519), tab container/persistence.
• External gpui-component checkout — Reusable UI components, macros, and bundled assets.
• crates/one_ui — Navop-owned composite components and product-specific UI.

Feature Crates (Backend + View Pairs)

Domain	Backend Crate	View Crate
Database	crates/db	crates/db_view
Terminal	crates/terminal	crates/terminal_view
SSH/SFTP	crates/ssh, crates/sftp	crates/sftp_view
Redis	—	crates/redis_view
MongoDB	—	crates/mongodb_view

Utilities

• reqwest_client — HTTP client wrapper around Zed's custom reqwest fork. Comes from the gpui-pre fork as the package gpui-pre-reqwest-client (lib name reqwest_client), patched in the root Cargo.toml; there is no longer a local crates/reqwest_client copy.
• crates/webview (gpui-wry) — WebView integration via Wry.
• crates/license_tool — License key generation and management.
• crates/story — Component gallery/showcase app (runs with cargo run from default members).
• examples/ — Standalone examples (hello_world, input, dialog_overlay, webview, system_monitor, focus_trap, etc.).

Application Initialization Flow

The startup sequence in main/src/main.rs and main/src/navop_app.rs is order-sensitive:

1. update::handle_update_command() — handle self-update CLI commands
2. load_env_files() — 仅开发构建从 CWD / 工作区加载 .env.local / .env
3. Application::new().with_assets(Assets) — create app with bundled assets
4. navop_app::init(cx) — tracing, HTTP client, then subsystem init:

• gpui_component::init(cx) — must be called before any UI component usage
• one_core::init(cx), one_ui::init(cx) — core and UI subsystem init
• db_view::chatdb::agents::init(cx) — chat DB agents
• Auth init → license init → AI provider state setup
• db::init_cache(cx) + disk cache cleanup task
• terminal_view::init(cx), redis_view::init(cx), mongodb_view::init(cx)
• Key bindings (shift-escape → ToggleZoom, cmd-w/ctrl-d → ClosePanel)
• TabContentRegistry global setup

5. setting_tab::init_settings(cx) — settings system
6. GlobalDbState::new() + cleanup task → cx.set_global()
7. db_view::init_ask_ai_notifier(cx) — Ask AI notifier
8. DatabaseViewPluginRegistry → cx.set_global()
9. Open window with Root::new(NavopApp, window, cx) — Root must be the outermost view

Architecture Patterns

Root View System

Every window's outermost view must be a Root. It manages sheets, dialogs, notifications, and keyboard navigation (Tab/Shift-Tab).

Dock System

Panel layout system with drag-and-drop, zoom, serialization:

• DockArea → DockItem tree (Split | Tabs | Panel)
• Panels implement PanelView trait
• PanelRegistry handles serialization/deserialization

Tab Container System

TabContainer (in one-core) manages multi-tab workflows with:

• TabContentRegistry global for registering tab content types
• TabContainerEvent for inter-tab communication
• Tab state persistence via one_core::tab_persistence (save/load)

Component Design

• Stateless preferred: Use RenderOnce trait when possible
• Size system: xs, sm, md (default), lg via Sizable trait
• Cursor convention: Buttons use default cursor (desktop convention), not pointer, unless link-style
• Styling: CSS-like API via Styled trait and ElementExt

Theme System

• Theme global singleton, light/dark mode
• Access via ActiveTheme trait: cx.theme()
• Covers colors (ThemeColor), syntax highlighting, fonts, border radius, shadows, scrollbar mode

Input System

Text input based on Rope (ropey crate) with:

• LSP integration (diagnostics, completion, hover)
• Tree-sitter syntax highlighting
• Variants: Input, NumberInput, OtpInput

Configuration

• Environment files: 仅开发构建加载 .env.local（优先）→ .env（回退），搜索 CWD 与工作区根目录；Release 不读取环境文件
• Build-time config: SUPABASE_URL, SUPABASE_ANON_KEY can be baked in at compile time, overridden at runtime
• Update URL: the implementation currently accepts the legacy NAVOP_UPDATE_URL env var for compatibility
• Log level: RUST_LOG env var (default: info)

Language Convention

• 简体中文：AI 回复、代码注释、Git 提交信息、文档等一律使用简体中文
• 唯一例外：代码标识符（变量名、函数名、类名等）遵循项目既有英文命名约定

编码规约与开发准则

开始编码前必须先阅读 AGENTS.md，其中包含完整的编码规约、质量标准、工作流程、MCP 工具集成规则和验证机制。