mirror of
https://github.com/PR0M3TH3AN/Marlin.git
synced 2025-09-09 07:38:50 +00:00
201 lines
8.2 KiB
Markdown
201 lines
8.2 KiB
Markdown
# Marlin — TUI + Query-DSL + Templates
|
||
|
||
**Integration Specification · v0.1 (2025-05-18)**
|
||
|
||
---
|
||
|
||
## 0 · Scope
|
||
|
||
This document turns the **concept sketch** (suck-less TUI) **plus** the new
|
||
*relationship-template* and *positive/negative filter* ideas into a concrete
|
||
development plan that extends the existing Marlin code-base without breaking
|
||
CLI workflows.
|
||
|
||
---
|
||
|
||
## 1 · Feature Set
|
||
|
||
| Epic | Deliverable | Short Description |
|
||
| -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
||
| **T-1** | **Marlin-TUI** binary | One-screen, tiling, key-centred interface (sketch in §2). |
|
||
| **Q-1** | **Query DSL v2** | Lexer + parser + planner supporting `AND/OR`, `NOT`, parentheses, ranges, comparison ops on `size`, `mtime`… |
|
||
| **T-2** | **Relationship templates** | Named templates with typed fields (key + value-type) that auto-populate attributes when applied. |
|
||
| **Glue** | Shared **`libmarlin`** crate | Re-export public APIs so both CLI and TUI call the same Rust functions. |
|
||
|
||
These map cleanly onto the public roadmap:
|
||
|
||
* T-1 → *Phase 6: Search DSL v2 & Smart Views* (UI portion)
|
||
* Q-1 → *Phase 6* (parser)
|
||
* T-2 → *Phase 7: Structured Workflows* (templates subsection)
|
||
|
||
---
|
||
|
||
## 2 · TUI Reference Layout & Key-Map
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Marlin ▸ ~/demo (q quit · ? help) │
|
||
├───────────────┬─────────────────────────────────────────────┤
|
||
│ Tags / Views │ Path / Name │ ⓘ Attributes │
|
||
│───────────────│────────────────────────┼────────────────────│
|
||
│ project │ api/design.md │ status=pending │
|
||
│ ├ alpha │ roadmap.xlsx │ reviewed=yes │
|
||
│ │ ├ draft │ ... │ tags=project/alpha │
|
||
│ │ └ final │ (42/812 shown) │ links: 2 outgoing │
|
||
│ <Views> │ grep: "(?i)todo" │ ───── Preview ───── │
|
||
│ • urgent │ │ - [ ] TODO write… │
|
||
└───────────────┴────────────────────────┴────────────────────┘
|
||
```
|
||
|
||
### Essential Keys
|
||
|
||
| Key | Effect | CLI equivalence |
|
||
| --------------- | ------------------------- | -------------------------------- |
|
||
| `/expr⏎` | Regex/FTS filter | `marlin search` |
|
||
| `;key=val⏎` | Attr filter | `marlin search attr:key=val` |
|
||
| `:` | Command prompt | raw CLI passthrough |
|
||
| `Space` | Mark/unmark | adds to in-memory selection list |
|
||
| `:tag foo/bar⏎` | Tag marked files | `marlin tag` |
|
||
| `Enter` | open file in `$EDITOR` | — |
|
||
| `Tab` | toggle right preview pane | — |
|
||
|
||
Full table lives in **`docs/tui_keys.md`** (auto-generated from
|
||
`src/tui/keymap.rs`).
|
||
|
||
---
|
||
|
||
## 3 · Architecture Impact
|
||
|
||
### 3.1 Crate refactor (Week 1)
|
||
|
||
```
|
||
marlin/
|
||
├── cli-bin/ ← binary crate (keeps current main.rs)
|
||
├── tui-bin/ ← NEW binary crate (Marlin-TUI)
|
||
├── libmarlin/ ← NEW library: DB helpers, scan, query, templates
|
||
└── Cargo.toml
|
||
```
|
||
|
||
*Export surface*:
|
||
|
||
```rust
|
||
pub struct Marlin { /* connection, config … */ }
|
||
impl Marlin {
|
||
pub fn search(&self, q: Query) -> Result<Vec<PathBuf>>;
|
||
pub fn tag(&self, files: &[PathBuf], tag: &str) -> Result<()>;
|
||
pub fn apply_template(&self, files: &[PathBuf], tpl: &Template) -> Result<()>;
|
||
/* … */
|
||
}
|
||
```
|
||
|
||
CLI keeps 100 % of its flags; it just calls `libmarlin`.
|
||
|
||
TUI links against the same crate → zero business-logic duplication.
|
||
|
||
---
|
||
|
||
### 3.2 Query-DSL v2 (Week 2-3)
|
||
|
||
* **Lexer:** [`logos`](https://crates.io/crates/logos) (<500 LOC).
|
||
* **Parser:** `nom` (top-down precedence climbing).
|
||
* **AST → Plan:**
|
||
|
||
```rust
|
||
struct Plan {
|
||
fts_match: Option<String>, // tags_text/path/attrs_text
|
||
sql_where: Vec<String>, // files.size > ?, files.mtime BETWEEN ? ?
|
||
params: Vec<SqlArg>,
|
||
}
|
||
```
|
||
* **Planner** decides when to fall back to pure SQL (e.g. `size>1M AND NOT tag:archive` uses an FTS sub-query joined on rowid).
|
||
|
||
Backwards compatibility: old space-separated syntax is parsed first; if it fails,
|
||
DSL v2 is attempted, so no user breakage.
|
||
|
||
---
|
||
|
||
### 3.3 Templates (Week 4)
|
||
|
||
**Schema (migration 0005):**
|
||
|
||
```sql
|
||
CREATE TABLE templates (
|
||
id INTEGER PRIMARY KEY,
|
||
name TEXT NOT NULL UNIQUE,
|
||
description TEXT
|
||
);
|
||
CREATE TABLE template_fields (
|
||
id INTEGER PRIMARY KEY,
|
||
template_id INTEGER NOT NULL REFERENCES templates(id),
|
||
key TEXT NOT NULL,
|
||
value_type TEXT NOT NULL -- 'text' | 'int' | 'date'
|
||
);
|
||
```
|
||
|
||
**CLI additions**
|
||
|
||
```
|
||
marlin template list|show|add|rm
|
||
marlin template apply <name> <glob>
|
||
```
|
||
|
||
`Templater` helper validates type coercion before inserting into `attributes`.
|
||
|
||
TUI: `:apply <tpl>` applies to marked files and prompts inline for field values
|
||
(stenographic prompt à la `git commit --template`).
|
||
|
||
---
|
||
|
||
## 4 · Implementation Phases & Timeline
|
||
|
||
| Week | Milestone / Task | Owner | Exit Criteria |
|
||
| ---- | ------------------------------------------ | -------- | ------------------------- |
|
||
| 1 | Split repo into `libmarlin`, adapt CLI | core dev | `cargo test --all` green |
|
||
| 2 | Lexer + unit tests | core dev | 95 % coverage |
|
||
| 3 | Parser + Planner; replace `run_search()` | core dev | DSL green tests pass |
|
||
| 4 | Template schema, CLI, tests | DB dev | `template apply` e2e test |
|
||
| 5 | **TUI MVP**<br>draw loop + panes + key nav | UI dev | Can browse & open files |
|
||
| 6 | TUI ↔ Marlin API glue<br>mark, tag, search | UI dev | All key-map smoke tests |
|
||
| 7 | Preview cache, file-watch refresh | UI dev | CPU < 5 % idle load |
|
||
| 8 | Docs refresh, release notes | all | v0.2.0 tag |
|
||
|
||
---
|
||
|
||
## 5 · Testing & CI
|
||
|
||
* **DSL golden-file tests** (`tests/dsl/*.txt` → expected SQL).
|
||
* **SQLite snapshot tests** for templates.
|
||
* **TUI headless tests** via `termwiz`’s `TerminalTest` harness.
|
||
* GitHub Actions matrix unchanged; new crate just builds in.
|
||
|
||
---
|
||
|
||
## 6 · Risks & Mitigations
|
||
|
||
| Risk | Impact | Mitigation |
|
||
| ---------------------------- | -------------- | ------------------------------------------------------------ |
|
||
| Parser ambiguity | broken queries | formal grammar + fuzzy tests |
|
||
| TUI performance on huge dirs | lag | incremental drawing + LRU file stat cache |
|
||
| Schema lock-in for templates | hard to evolve | keep `value_type` generic (text) until needs prove otherwise |
|
||
|
||
---
|
||
|
||
## 7 · What Stays Back-Compatible?
|
||
|
||
* **CLI syntax**: existing commands & search strings still work.
|
||
* **Database**: 0005 migration is additive.
|
||
* **Automation scripts**: unchanged; TUI is *optional* (`marlin-tui` binary).
|
||
|
||
---
|
||
|
||
## 8 · Why It’s Worth It
|
||
|
||
* **Differentiator**: Few local-first tools combine rich metadata, SQL-grade
|
||
filtering, and both script-friendly CLI *and* keyboard-driven TUI.
|
||
* **Gateway to GUI**: The API we expose for TUI is the same one the
|
||
future GTK/Qt desktop app can use.
|
||
|
||
---
|
||
|
||
**Let the hacking begin!**
|