feat: added a command to send dm with attachment to admin to help disputes solving - added some docs for AI generated code

Author: arkanoider

Cargo.lock

@@ -47,6 +47,9 @@ pretty_env_logger = "0.5.0"
 sqlx = { version = "0.8.6", features = ["sqlite", "runtime-tokio-rustls"] }
 bip39 = { version = "2.2.0", features = ["rand"] }
 dirs = "6.0.0"
+chacha20poly1305 = "0.10.1"
+rand_core = "0.6.4"
+bitcoin = "0.32.2"
 
 [package.metadata.release]
 # (Default: true) Set to false to prevent automatically running `cargo publish`.

Cargo.toml

@@ -0,0 +1,130 @@
+## Architecture & Code Structure
+
+This document describes the internal structure of `mostro-cli`, how major modules interact, and the main data/control flows. It is intentionally high-level to stay stable across refactors.
+
+### Entry point and CLI wiring
+
+- **`src/main.rs`**
+  - Initializes the async runtime and delegates to `cli::run()`.
+  - Very thin; most logic is in `src/cli.rs`.
+
+- **`src/cli.rs`**
+  - Declares submodules for each logical command group: `add_invoice`, `adm_send_dm`, `conversation_key`, `dm_to_user`, `get_dm`, `get_dm_user`, `last_trade_index`, `list_disputes`, `list_orders`, `new_order`, `orders_info`, `rate_user`, `restore`, `send_dm`, `send_admin_dm_attach`, `send_msg`, `take_dispute`, `take_order`.
+  - Defines:
+    - `Context`: runtime dependencies required by commands (Nostr client, keys, trade index, DB pool, optional admin context keys, and Mostro pubkey).
+    - `Cli`: top-level arguments parsed by `clap` (subcommand, verbosity, Mostro pubkey override, relay list, PoW, secret mode).
+    - `Commands`: enum containing all subcommands and their structured arguments.
+  - `run()`:
+    - Parses CLI args via `Cli::parse()`.
+    - Constructs a `Context` using `init_context(&cli)`.
+    - Dispatches: `if let Some(cmd) = &cli.command { cmd.run(&ctx).await?; }`.
+  - `init_context()`:
+    - Sets environment variables from CLI flags (e.g. `MOSTRO_PUBKEY`, `RELAYS`, `POW`, `SECRET`).
+    - Connects to SQLite via `db::connect()`.
+    - Loads identity and per-trade keys from the local `users` table.
+    - Optionally loads `ADMIN_NSEC` into `context_keys` for admin commands.
+    - Resolves `MOSTRO_PUBKEY` via CLI flag or environment.
+    - Connects to Nostr relays via `util::connect_nostr()`.
+
+### Utilities and shared infrastructure
+
+- **`src/util/mod.rs`**
+  - Organizes utility modules:
+    - `events`: event filtering and retrieval from Nostr.
+    - `messaging`: higher-level DM helpers (gift-wrapped messages, admin keys, etc.).
+    - `misc`: small helpers such as `get_mcli_path` and string utilities.
+    - `net`: Nostr network connection setup.
+    - `storage`: thin storage helpers for orders and DMs.
+    - `types`: small shared enums/wrappers.
+  - Re-exports commonly used symbols (`create_filter`, `send_dm`, `connect_nostr`, `save_order`, etc.) so other modules can import from `crate::util` directly.
+
+- **`src/util/storage.rs`**
+  - `save_order(order, trade_keys, request_id, trade_index, pool)`:
+    - Wraps `Order::new` to insert/update an order row.
+    - Logs created order IDs.
+    - Updates the `User`'s `last_trade_index` in the `users` table.
+  - `run_simple_order_msg(command, order_id, ctx)`:
+    - Convenience wrapper that forwards to `cli::send_msg::execute_send_msg(...)` for simple order messages (e.g. `FiatSent`, `Release`, `Cancel`, `Dispute`).
+  - `admin_send_dm(ctx, msg)`:
+    - Uses `util::messaging::get_admin_keys` and `util::send_dm` to send an admin DM via Nostr.
+
+- **`src/util/types.rs`**
+  - `Event` enum:
+    - Wraps `SmallOrder`, `Dispute`, and a `Message` tuple `(Message, u64, PublicKey)` for use in parsers and event handling.
+  - `ListKind` enum:
+    - Identifies what is being listed: `Orders`, `Disputes`, `DirectMessagesUser`, `DirectMessagesAdmin`, `PrivateDirectMessagesUser`.
+  - `MessageType` (internal to `util`) distinguishes DM/gift-wrap styles.
+
+### Database layer
+
+- **`src/db.rs`**
+  - Connection:
+    - `connect()` creates or opens `mcli.db` in the CLI data directory from `get_mcli_path()`.
+    - On first run, it creates the `orders` and `users` tables via raw SQL.
+    - On subsequent runs, it applies a small migration to drop legacy `buyer_token`/`seller_token` columns if present.
+  - Models:
+    - `User`:
+      - Represents the local identity (mnemonic, root pubkey, last trade index).
+      - Handles creation (`User::new`), loading (`User::get`), updating (`save`), and key derivation helpers (identity keys and per-trade keys using `nip06`).
+    - `Order`:
+      - Represents cached orders with fields mapped to the `orders` table.
+      - Provides `new`, `insert_db`, `update_db`, fluent setters, `save`, `save_new_id`, `get_by_id`, `get_all_trade_keys`, and `delete_by_id`.
+  - See `database.md` for schema details.
+
+### Parsers and protocol types
+
+- **`src/parser/*`**
+  - Interpret raw Nostr events into higher-level `Event` variants based on `mostro_core` types.
+  - Responsibility split:
+    - `orders.rs`: parsing order-related events.
+    - `disputes.rs`: parsing dispute events.
+    - `dms.rs`: parsing direct messages.
+    - `common.rs`: shared parsing helpers.
+    - `mod.rs`: module glue.
+
+### Lightning integration
+
+- **`src/lightning/mod.rs`**
+  - Houses Lightning Network–specific helpers used by order flows and invoice handling (exact functions depend on the current version of the file).
+  - Typically used by `add_invoice`, `new_order`, and `take_order` modules.
+
+### Command modules
+
+Each file in `src/cli/` encapsulates the logic of a specific feature or a group of related commands:
+
+- Order-related: `add_invoice.rs`, `list_orders.rs`, `new_order.rs`, `take_order.rs`, `orders_info.rs`, `rate_user.rs`, `restore.rs`, `last_trade_index.rs`.
+- Disputes and admin: `list_disputes.rs`, `take_dispute.rs`, `adm_send_dm.rs`.
+- Messaging: `send_dm.rs`, `send_msg.rs`, `dm_to_user.rs`, `get_dm.rs`, `get_dm_user.rs`, `send_admin_dm_attach.rs`, `conversation_key.rs`.
+
+Each module exports an `execute_*` function that `Commands::run` calls. This keeps `src/cli.rs` as a central router while pushing feature logic into focused files.
+
+### Typical flow: creating a new order
+
+1. User runs `mostro-cli neworder ...`.
+2. `clap` parses CLI arguments into `Cli` and `Commands::NewOrder { ... }`.
+3. `cli::run()` calls `init_context()` to build `Context` (DB, keys, Nostr client, Mostro pubkey).
+4. `Commands::run` matches `Commands::NewOrder` and calls `execute_new_order(...)`.
+5. The handler:
+   - Uses `mostro_core` types to construct an order message.
+   - Sends it to the Mostro backend over Nostr via `util::connect_nostr`/messaging helpers.
+   - Persists or updates the local representation via `util::save_order` and `db::Order`.
+
+### Extension guidelines
+
+When adding new features:
+
+- **New command**:
+  - Add a variant to `Commands` in `src/cli.rs`.
+  - Add the corresponding `execute_*` function in a `src/cli/*.rs` module.
+  - Extend the `Commands::run` match arm.
+  - Update `docs/commands.md` to keep documentation in sync.
+
+- **New database fields / tables**:
+  - Update `connect()` schema creation and migrations in `src/db.rs`.
+  - Extend the relevant model structs and methods.
+  - Update `docs/database.md`.
+
+- **New protocol/event type**:
+  - Extend `util::types::Event` and the relevant parser module in `src/parser/*`.
+  - Adjust listing or DM flows as needed.
+

docs/architecture.md

@@ -0,0 +1,212 @@
+## CLI Commands Reference
+
+This document lists all `mostro-cli` subcommands defined in `src/cli.rs`, their main arguments, and the Rust handler that implements each command. Use this when wiring new commands or changing existing flows.
+
+All commands are part of the `Commands` enum and are dispatched via `Commands::run(&self, ctx: &Context)`.
+
+### Orders
+
+- **`listorders`**
+  - **Description**: Requests open orders from the configured Mostro pubkey.
+  - **Args**:
+    - `--status <STRING>`: Optional order status filter.
+    - `--currency <STRING>`: Optional fiat currency code.
+    - `--kind <STRING>`: Optional order kind (buy/sell).
+  - **Handler**: `execute_list_orders(kind, currency, status, ctx)` in `src/cli/list_orders.rs`.
+
+- **`neworder`**
+  - **Description**: Create a new buy/sell order on Mostro.
+  - **Args**:
+    - `--kind <STRING>`: Order kind (e.g. `buy` or `sell`).
+    - `--amount <i64>`: Sats amount; `0` means market price.
+    - `-c, --fiat-code <STRING>`: Fiat currency code.
+    - `--fiat-amount <RANGE>`: Fiat amount or range, validated by `check_fiat_range`.
+    - `-m, --payment-method <STRING>`: Payment method identifier.
+    - `--premium <i64>`: Premium on the price (can be negative).
+    - `--invoice <STRING>`: Optional Lightning invoice.
+    - `--expiration-days <i64>`: Expiration time in days for pending orders.
+  - **Handler**: `execute_new_order(...)` in `src/cli/new_order.rs`.
+
+- **`takesell`**
+  - **Description**: Take a sell order from a Mostro pubkey.
+  - **Args**:
+    - `--order-id <UUID>`: Order identifier.
+    - `--invoice <STRING>`: Optional Lightning invoice.
+    - `--amount <u32>`: Fiat amount to buy.
+  - **Handler**: `execute_take_order(order_id, Action::TakeSell, invoice, amount, ctx)` in `src/cli/take_order.rs`.
+
+- **`takebuy`**
+  - **Description**: Take a buy order from a Mostro pubkey.
+  - **Args**:
+    - `--order-id <UUID>`: Order identifier.
+    - `--amount <u32>`: Fiat amount to sell.
+  - **Handler**: `execute_take_order(order_id, Action::TakeBuy, &None, amount, ctx)` in `src/cli/take_order.rs`.
+
+- **`addinvoice`**
+  - **Description**: Buyer adds a new invoice to receive the payment.
+  - **Args**:
+    - `--order-id <UUID>`: Order identifier.
+    - `--invoice <STRING>`: Lightning invoice.
+  - **Handler**: `execute_add_invoice(order_id, invoice, ctx)` in `src/cli/add_invoice.rs`.
+
+- **`fiatsent`**
+  - **Description**: Send a "fiat sent" message to confirm payment to the counterparty.
+  - **Args**:
+    - `--order-id <UUID>`: Order identifier.
+  - **Handler**: `util::run_simple_order_msg(Commands::FiatSent { .. }, Some(order_id), ctx)`.
+
+- **`release`**
+  - **Description**: Settle the hold invoice and pay to the buyer.
+  - **Args**:
+    - `--order-id <UUID>`: Order identifier.
+  - **Handler**: `util::run_simple_order_msg(Commands::Release { .. }, Some(order_id), ctx)`.
+
+- **`cancel`**
+  - **Description**: Cancel a pending order.
+  - **Args**:
+    - `--order-id <UUID>`: Order identifier.
+  - **Handler**: `util::run_simple_order_msg(Commands::Cancel { .. }, Some(order_id), ctx)`.
+
+- **`ordersinfo`**
+  - **Description**: Request detailed information for specific orders.
+  - **Args**:
+    - `--order-ids <UUID>...`: One or more order IDs.
+  - **Handler**: `execute_orders_info(order_ids, ctx)` in `src/cli/orders_info.rs`.
+
+### Disputes
+
+- **`dispute`**
+  - **Description**: Start a dispute for an order.
+  - **Args**:
+    - `--order-id <UUID>`: Order identifier.
+  - **Handler**: `util::run_simple_order_msg(Commands::Dispute { .. }, Some(order_id), ctx)`.
+
+- **`listdisputes`**
+  - **Description**: Request open disputes from the Mostro pubkey.
+  - **Args**: None.
+  - **Handler**: `execute_list_disputes(ctx)` in `src/cli/list_disputes.rs`.
+
+### Direct messages (user)
+
+- **`getdm`**
+  - **Description**: Get the latest direct messages.
+  - **Args**:
+    - `--since <i64>`: Minutes back from now to query (default: 30).
+    - `--from-user`: If true, get messages from the counterparty instead of Mostro.
+  - **Handler**: `execute_get_dm(since, false, from_user, ctx)` in `src/cli/get_dm.rs`.
+
+- **`getdmuser`**
+  - **Description**: Get direct messages sent to any trade keys.
+  - **Args**:
+    - `--since <i64>`: Minutes back from now to query (default: 30).
+  - **Handler**: `execute_get_dm_user(since, ctx)` in `src/cli/get_dm_user.rs`.
+
+- **`senddm`**
+  - **Description**: Send a direct message to a user.
+  - **Args**:
+    - `--pubkey <NPUB/HEX>`: Pubkey of the counterpart.
+    - `--order-id <UUID>`: Order identifier (for context).
+    - `--message <STRING>...`: Message parts; joined with spaces.
+  - **Handler**: `execute_send_dm(PublicKey::from_str(pubkey)?, ctx, order_id, &msg)` in `src/cli/send_dm.rs`.
+
+- **`dmtouser`**
+  - **Description**: Send a gift-wrapped direct message to a user.
+  - **Args**:
+    - `--pubkey <NPUB/HEX>`: Recipient pubkey.
+    - `--order-id <UUID>`: Order id to derive ephemeral keys.
+    - `--message <STRING>...`: Message parts; joined with spaces.
+  - **Handler**: `execute_dm_to_user(PublicKey::from_str(pubkey)?, &ctx.client, order_id, &msg, &ctx.pool)` in `src/cli/dm_to_user.rs`.
+
+### Direct messages (admin / solver)
+
+- **`getadmindm`**
+  - **Description**: Get the latest direct messages for admin.
+  - **Args**:
+    - `--since <i64>`: Minutes back from now to query (default: 30).
+    - `--from-user`: If true, get messages from the counterparty instead of Mostro.
+  - **Handler**: `execute_get_dm(since, true, from_user, ctx)` in `src/cli/get_dm.rs`.
+
+- **`admsenddm`** *(admin only)*
+  - **Description**: Send a gift-wrapped direct message to a user as admin/solver.
+  - **Args**:
+    - `--pubkey <NPUB/HEX>`: Recipient pubkey.
+    - `--message <STRING>...`: Message parts; joined with spaces.
+  - **Handler**: `execute_adm_send_dm(PublicKey::from_str(pubkey)?, ctx, &msg)` in `src/cli/adm_send_dm.rs`.
+
+- **`sendadmindmattach`** *(admin only)*
+  - **Description**: Send an admin DM with an encrypted attachment stored on a Blossom server.
+  - **Args**:
+    - `--pubkey <NPUB/HEX>`: Admin recipient pubkey.
+    - `--order-id <UUID>`: Order id to derive the correct trade key.
+    - `--file <PATH>`: Path to the file to encrypt and upload.
+  - **Handler**: `execute_send_admin_dm_attach(PublicKey::from_str(pubkey)?, ctx, order_id, file)` in `src/cli/send_admin_dm_attach.rs`.
+
+### Identity & keys
+
+- **`conversationkey`**
+  - **Description**: Get the conversation key for direct messaging with a user.
+  - **Args**:
+    - `--pubkey <NPUB/HEX>`: Counterparty pubkey.
+  - **Handler**: `execute_conversation_key(&ctx.trade_keys, PublicKey::from_str(pubkey)?)` in `src/cli/conversation_key.rs`.
+
+- **`getlasttradeindex`**
+  - **Description**: Get last trade index of the user.
+  - **Args**: None.
+  - **Handler**: `execute_last_trade_index(&ctx.identity_keys, ctx.mostro_pubkey, ctx)` in `src/cli/last_trade_index.rs`.
+
+- **`getlasttradeprivkey`**
+  - **Description**: Get private key of the last trade index public key.
+  - **Args**: None.
+  - **Handler**: `execute_last_trade_index_private_key(ctx)` in `src/cli/last_trade_index.rs`.
+
+### Session & restore
+
+- **`restore`**
+  - **Description**: Restore session to recover all pending orders and disputes.
+  - **Args**: None.
+  - **Handler**: `execute_restore(&ctx.identity_keys, ctx.mostro_pubkey, ctx)` in `src/cli/restore.rs`.
+
+### Admin / solver dispute management
+
+- **`admcancel`** *(admin only)*
+  - **Description**: Cancel an order / dispute as admin.
+  - **Args**:
+    - `--order-id <UUID>`: Order identifier.
+  - **Handler**: `execute_admin_cancel_dispute(order_id, ctx)` in `src/cli/take_dispute.rs`.
+
+- **`admsettle`** *(admin only)*
+  - **Description**: Settle a seller's hold invoice.
+  - **Args**:
+    - `--order-id <UUID>`: Order identifier.
+  - **Handler**: `execute_admin_settle_dispute(order_id, ctx)` in `src/cli/take_dispute.rs`.
+
+- **`admaddsolver`** *(admin only)*
+  - **Description**: Add a new dispute solver.
+  - **Args**:
+    - `--npubkey <NPUB>`: Nostr pubkey of the solver.
+  - **Handler**: `execute_admin_add_solver(npubkey, ctx)` in `src/cli/take_dispute.rs`.
+
+- **`admtakedispute`** *(admin/solver only)*
+  - **Description**: Admin or solver takes a pending dispute.
+  - **Args**:
+    - `--dispute-id <UUID>`: Dispute identifier.
+  - **Handler**: `execute_take_dispute(dispute_id, ctx)` in `src/cli/take_dispute.rs`.
+
+### Rating
+
+- **`rate`**
+  - **Description**: Rate counterpart after a successful trade.
+  - **Args**:
+    - `--order-id <UUID>`: Order identifier.
+    - `--rating <u8>`: Rating from 1 to 5.
+  - **Handler**: `execute_rate_user(order_id, rating, ctx)` in `src/cli/rate_user.rs`.
+
+---
+
+If you add a new variant to the `Commands` enum:
+
+1. Add the subcommand and its arguments in `src/cli.rs`.
+2. Add its handler function in an appropriate `src/cli/*.rs` module.
+3. Extend the `Commands::run` match to call the handler.
+4. Update this `commands.md` file so documentation stays in sync for humans and AI tools.
+