How denisidoro/navi works
Project type and purpose
• From the file tree and README, navi is a Rust-based, open-source, interactive command-line cheatsheet tool. It ships as a single CLI binary, integrates with various shells (bash, zsh, fish, PowerShell, Nu, Elvish), leverages external fuzzy-finder tools (fzf or skim), and can fetch or manage cheatsheet repositories (local or remote).
Key top-level directories and patterns
• src/bin/main.rs: entry point for the CLI executable.
• src/commands/: implements subcommands (core actor logic, functional commands, preview, repo, info, shell, temp).
• src/clients/: HTTP clients for external cheat services (cheat.sh, tldr).
• src/config/: CLI flags, environment variables, YAML config parsing.
• src/common/: shared utilities (filesystem, shell spawning, clipboard, URL, terminal, hashing).
• src/finder/: logic to locate and filter cheats from file system or remote sources.
• src/parser.rs & src/deser/: parsing the .cheat file syntax, deserializing into internal representations.
• shell/: shell widget scripts for various shells—how navi hooks into user’s shell.
• scripts/: automated tasks (install, test, release, docker).
• docs/ & tests/: user documentation and automated test cases.
Main components
a. User Interface Layer
• Shell widget scripts (bash, zsh, fish, PS1, nu, elv)
• Direct invocation of the navi binary in a terminal
b. navi Core (Rust Binary)
• CLI Parser & Dispatcher (src/bin/main.rs + structopt/clap)
• Command Modules (src/commands/*): core actor, functional transforms, preview renderers, repository management, info, shell execution
• Configuration Manager (src/config/*): loads CLI flags, env vars, YAML config
• Cheatsheet Finder (src/finder): scans local ~/.local/share/navi/cheats/, auto-updates remote repos via Git or HTTP
• Parser & Deserializer (src/parser.rs, src/deser): reads .cheat files into structures
• Data Structures (src/structures/*): in-memory representations of cheats, actions, suggestions
• Common Utilities (src/common/*): shell spawning, clipboard, terminal I/O, fs access
• External Clients (src/clients/*): fetch cheats from cheat.sh or tldr API
• Integration with fuzzy-finder: spawns fzf or skim as subprocess to let user filter suggestions
c. External Dependencies
• File system (local cheats directory, config files)
• Git (for repo import & updates)
• HTTP services (cheat.sh, tldr)
• fzf/skim (filters)
• Shell environment (executes chosen commands)
Relationships and data flow
• User presses widget keybind or runs navi → Shell widget or CLI passes control to the navi binary
• Binary bootstraps: loads configuration → scans local cheats (and optionally remote via Git/HTTP) → parses .cheat files → builds internal structures
• User navigates suggestions via fzf/skim subprocess → selection triggers preview or execution
• If user requests remote cheats, src/clients/* fetches data over HTTP and hands off to the parser
• Final command is output back to the shell for execution
• Repo commands (navi repo add, navi repo browse) invoke Git or HTTP and write to the local cheats directory
Architectural patterns and design principles
• Layered architecture: UI layer → CLI dispatch → business logic modules → data access (FS, HTTP, Git) → external tools
• Modular command handlers: each subcommand is a separate module (easily extensible)
• Separation of concerns: parsing/deserialization, CLI config, core logic, client I/O, common utilities
• Plugin-like shell integration: shell-specific scripts delegate to the same binary
Technologies, frameworks, libraries
• Rust and Cargo
• structopt / clap (CLI parsing)
• serde / serde_yaml (deserialization of .cheat files & config)
• Git2 or calling out to the git CLI (repo management)
• reqwest or similar HTTP client (cheat.sh, tldr)
• fzf / skim subprocess integration
• Shell scripting for integration (shell/ directory)