1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
//! # Padz Architecture: CLI / Logic Separation
//!
//! Padz is a **UI-agnostic note-taking library**. This is not a CLI application that happens
//! to have some library code—it's a library that happens to have a CLI client.
//!
//! ## Workspace Structure
//!
//! Padz is organized as a Cargo workspace with two crates:
//! - `crates/padz/` — This core library (UI-agnostic business logic)
//! - `crates/padz-cli/` — The CLI tool (depends on this library)
//!
//! ## The Problem
//!
//! Shell programs tend to conflate interface and logic. Before you know it, logic is outputting
//! strings all over the place and calculations are converting strings to integers. This makes
//! the program unwieldy and hard to test.
//!
//! ## The Solution: Strict Layering
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────┐
//! │ CLI Layer (crates/padz-cli/) │
//! │ - Parses arguments, formats output, handles terminal I/O │
//! │ - The ONLY place that knows about stdout/stderr/exit codes │
//! └─────────────────────────────────────────────────────────────┘
//! │
//! ▼
//! ┌─────────────────────────────────────────────────────────────┐
//! │ API Layer (api.rs) │
//! │ - Thin facade over commands │
//! │ - Normalizes inputs (indexes → UUIDs) │
//! │ - Returns structured Result<CmdResult> │
//! └─────────────────────────────────────────────────────────────┘
//! │
//! ▼
//! ┌─────────────────────────────────────────────────────────────┐
//! │ Command Layer (commands/*.rs) │
//! │ - Pure business logic │
//! │ - Operates on Rust types, returns Rust types │
//! │ - No I/O assumptions whatsoever │
//! └─────────────────────────────────────────────────────────────┘
//! │
//! ▼
//! ┌─────────────────────────────────────────────────────────────┐
//! │ Storage Layer (store/) │
//! │ - Abstract DataStore trait │
//! │ - FileStore (production), InMemoryStore (testing) │
//! └─────────────────────────────────────────────────────────────┘
//! ```
//!
//! ## Key Principle: No I/O Assumptions in Core
//!
//! From `api.rs` inward, code:
//! - Takes regular Rust function arguments
//! - Returns regular Rust types (`Result<CmdResult>`)
//! - **Never** writes to stdout/stderr
//! - **Never** calls `std::process::exit`
//! - **Never** assumes a terminal environment
//!
//! This means the same core could serve a REST API, a browser app, or any other UI.
//!
//! ## The Index System
//!
//! To remain ergonomic, padz uses a dual ID system mapping user-friendly display indexes
//! (`1`, `p1`, `d1`) to stable UUIDs at the data store level.
//! See [`index`] module for details.
//!
//! ## Data Flow Example: `padz delete 1`
//!
//! 1. **CLI**: `clap` parses `1`. `handle_delete` receives `vec!["1"]`.
//! 2. **API**: `parse_selectors` maps `"1"` → `PadSelector::Index(Regular(1))`.
//! 3. **Command**: Resolves to UUID, checks protection, marks as deleted.
//! 4. **Return**: `CmdResult` with message "Deleted 1 pad".
//! 5. **CLI**: Renders the message to terminal.
//!
//! ## Testing Strategy
//!
//! | Layer | Test Type | What to Test |
//! |-------|-----------|--------------|
//! | CLI | Integration | Arg parsing, output formatting |
//! | API | Unit | Dispatch correctness, input normalization |
//! | Commands | Unit | Business logic, state transitions |
//! | Store | Unit | Read/write operations, sync behavior |
//!
//! ## Development Workflow
//!
//! When implementing features, work **inside-out**:
//!
//! 1. **Logic**: Implement and fully test in `commands/<cmd>.rs`
//! 2. **API**: Add facade method in `api.rs`, test dispatch
//! 3. **CLI**: Add handler in CLI crate's `commands.rs`, test arg parsing and output
//!
//! ## Module Overview
//!
//! - [`api`]: The API facade—entry point for all operations. Also handles selector parsing.
//! - [`commands`]: Business logic for each command
//! - [`store`]: Storage abstraction and implementations. See module for hybrid store architecture.
//! - [`model`]: Core data types and content normalization
//! - [`index`]: Display indexing system (p1, 1, d1 notation)
//! - [`init`]: Scope detection and context initialization
//! - [`config`]: Configuration management
//! - [`editor`]: External editor integration
//! - [`clipboard`]: Cross-platform clipboard support
//! - [`error`]: Error types