keynobi: Instructions file for Codex

AGENTS.md

Keynobi is a macOS companion app for Android development: Gradle builds, logcat, devices, UI hierarchy, and an MCP server for AI clients. Tauri 2 (Rust, tokio) backend, SolidJS + TypeScript + Vite frontend, ts-rs for IPC types, rmcp for MCP.

Commands

npm ci                     # install
npm run tauri dev          # run the app (first Rust build takes minutes)
npm run dev:web            # frontend only, against the mock backend
npm run generate:bindings  # after changing Rust models; commit src/bindings/

Where to Look

Each reference doc ends with Known Gaps: rules the code does not meet yet. Do not copy a known gap into new code.

Key Rules

• Layering: components → stores/services → src/lib/tauri-api.ts → Tauri commands → Rust services. Only tauri-api.ts calls invoke; commands validate and delegate.
• IPC contract: a command change updates the Rust handler, generate_handler! in lib.rs, the tauri-api.ts wrapper, and the mock backend together. After changing Rust models, run npm run generate:bindings and npm run generate:ipc-fixtures; import IPC types from @/bindings and never edit generated files.
• One implementation per behavior: Tauri commands and MCP tools call the same service function. Never copy logic into mcp_server.rs.
• Process model: keynobi --mcp attaches to the running app when it can (the app serves the session on its own state) and otherwise runs standalone with its own state, which the GUI does not see. See references/MCP_SERVER.md § Modes.
• Untrusted input: validate identifiers with utils/validation.rs and paths with utils/path.rs (canonicalized, never raw starts_with). Arguments to adb shell are re-parsed by the device shell.
• Rust: no unwrap() in production code; new commands return Result<T, AppError>; never hold a Mutex across .await; every growing collection has a named cap.
• Frontend: register shortcuts with registerKeyAndAction() in App.tsx; build UI from @/components/ui primitives and theme tokens.
• User data: tests must never read or write ~/.keynobi. Unit tests get a temp data directory automatically (cfg(test) in settings_manager); integration tests must call tests/common::isolate_data_dir() first. CI fails if a test creates ~/.keynobi.