madora

Imported from 1Yie/madora (AGENTS.md). Install upstream with npx skills add 1Yie/madora. Copyright stays with the author.

Repository Guidelines

Project Overview

Madora is a Tauri v2 desktop app for Markdown editing with AI autocompletion. The frontend is React 19 + Vite 7 + TypeScript (strict mode), styled with Tailwind CSS v4 via shadcn/ui (radix-nova style, @base-ui/react primitives). The backend is Rust with 40+ Tauri commands across 8 modules. AI completions use a Fill-in-the-Middle (FIM) pattern with 5 provider implementations (OpenAI, Anthropic, DeepSeek, Kimi, Custom).

Architecture & Data Flow

Frontend (React/TypeScript)
    ↕ Tauri IPC (invoke + Channel<String> for streaming)
Commands (src-tauri/src/commands/) — thin wrappers
    ↕ service calls
Services (src-tauri/src/services/) — business logic
    ↕ model types
Models (src-tauri/src/models/) — serde serialization types

Provider chain (React → Tauri): main.tsx mounts ThemeProvider → ToastProvider → AiSettingsProvider → ProseThemeProvider → App. App renders a custom title bar + hash router. The single route / loads MainLayout → WorkspaceBrowser, which orchestrates the resizable sidebar (file tree) + content pane (editor/preview).

AI completion data flow: User types in CodeMirror → use-editor hook debounces input (80ms) → calls invoke('generate_completion_stream') with prefix/suffix → Rust AiCompletionService checks cache (15s TTL, 128 entries), deduplicates in-flight → delegates to CompletionProvider trait → PromptManager renders FIM templates → HTTP request to provider → SSE stream back through Channel<String> → rendered as inline ghost text via CodeMirror Decoration.widget.

State management: No global state library — React Context for providers, useState/useReducer for component state, EditorEntry registry pattern (unsaved-registry.ts) backed by Map<string, EditorEntry> with localStorage draft fallback.

Key Directories

Development Commands

Frontend validation with bun run build (runs tsc && vite build).

bun run dev          # Vite dev server (port 1420, HMR 1421)
bun run build        # tsc + vite build
bun run test         # Vitest
bun run test:watch   # Vitest watch mode
bun run tauri dev    # Tauri desktop shell (from repo root)
bun run tauri build  # Production build
bun run lint         # ESLint 10 flat config
bun run lint:fix     # ESLint with --fix
bun run format       # Prettier (tabs, single quotes, semicolons, trailingComma es5)

In src-tauri/:

cargo check          # Rust-only validation
cargo test           # Rust tests (includes git integration tests)

Code Conventions & Common Patterns

TypeScript / React

• TypeScript strict mode: strict, noUnusedLocals, noUnusedParameters, noFallthroughCasesInSwitch — unused locals/params are build errors.
• Imports: Use @/ alias (maps to src/). No relative imports outside immediate directory.
• UI primitives: All in src/components/ui/. Use cn() (clsx + tailwind-merge) for class composition, cva for variant slots, useRender + mergeProps for polymorphism (from @base-ui/react). Follow shadcn patterns.
• Error handling: Error calls surfaced via showErrorToast() from @/components/ui/toast. No error boundaries currently.
• Hooks: Custom hooks in src/hooks/. use-editor.tsx uses React 19 useEffectEvent for stable callbacks, useSyncExternalStore for subscription-based state.
• Side effects: Tauri invoke calls are async. useState/useReducer for local state. Commands return Result<T, string> from Rust.
• No form libraries: Forms built from primitives (Button, Input, Select, Switch, etc.).

Rust

• All #[tauri::command] are async fn (except greet, get_system_theme).
• Return type: Result<T, String> — errors are stringified, no custom error enum.
• Managed state: accessed via tauri::State<'_, T>, registered in app.rs.
• CompletionProvider trait: #[async_trait] pub trait CompletionProvider: Send + Sync with required request_fim_completion and default request_fim_completion_stream (calls non-stream by default). Providers are static singletons.
• Streaming: Uses Tauri Channel<String>. Provider callbacks are &mut dyn FnMut(String) -> Result<(), String>. Common SSE parser in providers/common.rs.
• AI caching: AiCompletionService holds Mutex<HashMap<CompletionCacheKey, CachedCompletion>>, 15s TTL, 128 max entries, with in-flight dedup via Arc<InFlightCompletionRequest>.
• Secure storage: API keys via OS keyring (keyring crate, service name "madora.ai"), cached in LazyLock<Mutex<HashMap>>.
• Path safety: All filesystem operations validate paths stay within workspace root via ensure_within_root + canonicalization.
• Encoding: File reads use chardetng for detection + encoding_rs for decoding. BOM handling. UTF-8 canonical.
• Prompt system: PromptManager resolves templates from XDG config dir with fallback to compiled-in defaults (include_str!). {{variable}} substitution via serde JSON flatten.

Git

• Conventional commits: Enforced via commitlint + husky commit-msg hook.
• Pre-commit format: lint-staged runs prettier --write on staged *.{js,jsx,ts,tsx,vue,json,css,scss,md} files.

Important Files

Runtime/Tooling Preferences

Testing & QA

Frontend tests (Vitest)

• Framework: Vitest 4, happy-dom DOM environment, @testing-library/react 16, @testing-library/user-event 14, @testing-library/jest-dom 6.
• Setup: src/__tests__/setup.ts polyfills browser APIs (ResizeObserver, IntersectionObserver, matchMedia) and mocks @tauri-apps/api/core (Channel, invoke) so tests run without Tauri.
• Test location: src/__tests__/*.test.{ts,tsx}.
• Types of tests:
  • Pure function tests (path-utils.test.ts, git-utils.test.ts, editor-utils.test.ts): Test helper functions by replicating implementations locally. No component rendering.
  • Component tests (git-tab-commit.test.tsx, file-explorer-sidebar.test.tsx, workspace-browser.test.tsx, toast.test.tsx): Render components with mocked Tauri invoke and provider wrappers. Use @testing-library/react (render, waitFor, screen).
• Running: bun run test or vitest.

Rust tests

• Integration tests: src-tauri/tests/git_integration.rs uses tempfile + real git2 + subprocess git CLI. Tests init/add/commit/status/log/branch/merge/conflict detection.
• Rust unit tests: Inline in provider/service modules with mock HTTP responses.
• Running: cargo test from src-tauri/.

Build verification

• bun run build runs tsc && vite build — TypeScript errors fail the build.
• No dedicated E2E tests exist.