development.md

Development

toolstash is a Rust terminal app built with Ratatui and Crossterm.

Setup

From the repo root:

cargo build
cargo test

Run locally:

cargo run
cargo run -- calc
cargo run -- --theme nord

Install from the checkout:

cargo install --path .

Dependencies

Core UI:

• ratatui
• crossterm

Feature dependencies:

• regex for the regex tester.
• ureq for the HTTP client.
• serde_json for OpenAPI JSON import.

The database browser shells out to native clients instead of linking database drivers:

• sqlite3
• psql
• mysql
• duckdb

Tests that need an optional native client skip the integration path when that client is not available.

Common Checks

Run all tests:

cargo test

Run the architecture checks:

cargo test --test architecture

Run one tool's tests:

cargo test --test tools_calc
cargo test --test tools_api

Format:

cargo fmt

Coding Shape

The project keeps each feature local:

src/tools/calc/
  model.rs
  controller.rs
  view.rs

Use the same split for new features:

• model.rs: data, parsing, formatting, persistence, external calls.
• controller.rs: tool state and key handling.
• view.rs: Ratatui drawing.

Shared primitives belong in src/core/ only when multiple tools or shell screens need them.

Persistence

Use core::fs::read_config and core::fs::write_config for files under the toolstash config directory. Writes are best-effort so the app does not crash because a setting or scratchpad file could not be saved.

Prefer formats that remain readable and recoverable. Existing persistent files favor line-oriented text and stable separators over opaque binary data.

User Experience

New tools should feel native to the shell:

• Use navigate mode for commands and edit mode for text entry.
• Keep Enter as "type into this box" where possible.
• Keep Esc as "leave this box or screen".
• Implement keys() so ? is complete.
• Implement status() so the bottom row always says what is happening.
• Implement tile() so the dashboard shows useful recent state.
• Implement y and p only when copy/paste has obvious meaning.
• Keep settings session-only unless persisting them makes future answers more trustworthy.

Adding a Tool Checklist

1. Add src/tools/<name>/model.rs.
2. Add src/tools/<name>/controller.rs.
3. Add src/tools/<name>/view.rs.
4. Export the module in src/tools/mod.rs.
5. Add a Kind variant and list it in KINDS.
6. Wire construction and lookup in src/shell/app.rs.
7. Add tests under tests/tools/<name>.rs.
8. Run cargo test --test architecture.
9. Run the new tool test and any touched shared tests.