# Product Requirements Document — django-shreck

## 1. Vision

**django-shreck** is a reusable Django app that provides a rich Terminal User Interface (TUI)
as a replacement for Django's `shell_plus`. It brings visual, keyboard-driven interaction
to the Django ORM directly in the terminal — no browser required.

The name is a nod to Shrek's iconic green colour, which serves as the TUI's theme.

## 2. Target Users

| Persona | Description |
|---------|-------------|
| **Django Developer** | Day-to-day use for exploring data, debugging, and running management commands |
| **Team Lead / DBA** | Quick inspection of production data over SSH without needing a web admin |
| **New Team Member** | Discovering project models, fields, and management commands interactively |

## 3. Feature List

### P0 — Core (MVP)

| # | Feature | Description |
|---|---------|-------------|
| F1 | **Auto-imported models** | All Django models are automatically imported into the shell namespace on startup, just like `shell_plus`. Tab completion works out of the box. |
| F2 | **Interactive Python shell** | A fully functional Python REPL embedded inside the TUI. Supports `eval`/`exec`, history (↑/↓), and stores the last result in `_`. |
| F3 | **Scrollable table view** | When a `QuerySet` is returned, it is displayed as a scrollable `DataTable` with columns derived from model fields. Supports row selection. |

### P1 — Rich Display

| # | Feature | Description |
|---|---------|-------------|
| F4 | **Detail browser** | A single model instance is displayed as a scrollable key-value list of all field names, types, and values. Keyboard navigable. |
| F5 | **Inline editing** | When a variable holds a single model instance, the detail view allows editing field values and saving with `update_fields`. |
| F6 | **Side-by-side compare** | When exactly two model instances are returned (from a queryset of 2, or a list/tuple of 2), they are displayed side by side with differing values highlighted. |

### P2 — Power Features

| # | Feature | Description |
|---|---------|-------------|
| F7 | **Admin integration** | Pressing `a` opens the Django admin change page (single object) or changelist (queryset) in the default browser. URL is always shown in the TUI status bar. Falls back gracefully on headless systems. |
| F8 | **Management command browser** | Pressing `m` opens a panel listing all management commands. Selecting a command shows a form for its arguments (introspected from `ArgumentParser`). A "Run" button executes the command with captured output. |

### Smart Result Routing

The shell automatically routes results to the appropriate view:

```
Expression result
├── QuerySet (count=1)  → Detail view (editable)
├── QuerySet (count=2)  → Compare view
├── QuerySet (count>2)  → Table view
├── Single Model        → Detail view
├── List/Tuple of 2 Models → Compare view
└── Anything else       → Printed as repr() in shell output
```

## 4. Architecture

```
┌─────────────────────────────────────────────┐
│  ShreckApp (textual.app.App)                │
│  ┌───────────────────────────────────────┐  │
│  │  Header                               │  │
│  ├───────────────────────────────────────┤  │
│  │  ResultPanel                          │  │
│  │  ├── DetailWidget                     │  │
│  │  ├── TableWidget                      │  │
│  │  ├── CompareWidget                    │  │
│  │  └── CommandBrowserWidget             │  │
│  ├───────────────────────────────────────┤  │
│  │  ShellWidget                          │  │
│  │  ├── RichLog (output)                 │  │
│  │  └── Input (prompt)                   │  │
│  ├───────────────────────────────────────┤  │
│  │  Footer (keybindings)                 │  │
│  └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘
```

### Service Layer

| Service | Responsibility |
|---------|---------------|
| `ModelIntrospectionService` | Auto-discovers models via `django.apps`, introspects fields |
| `AdminUrlResolver` | Builds admin URLs for instances and querysets, opens browser |
| `CommandDiscoveryService` | Lists management commands, introspects their `ArgumentParser` |

### Message Flow

```
ShellWidget
  ──(eval/exec)──> result
  ──(post_message)──> ShowDetail / ShowTable / ShowCompare
                         │
                    ShreckApp (handler)
                         │
                    ResultPanel.show_detail() / show_table() / show_compare()
```

## 5. Tech Stack

| Component | Technology |
|-----------|-----------|
| TUI framework | [Textual](https://textual.textualize.io/) ≥ 1.0 |
| Python REPL | Built-in `eval`/`exec` with history (P0), [ptpython](https://github.com/prompt-toolkit/ptpython) integration (future) |
| ORM | Django ≥ 4.2 |
| Styling | Textual CSS (`.tcss` files) |
| Testing | pytest + pytest-django |
| Linting | Ruff |
| Packaging | Hatch (pyproject.toml) |

## 6. Non-Goals

- **Not a full IDE** — No file editing, no syntax-highlighted code editor.
- **Not a database GUI** — No raw SQL mode, no schema migrations UI.
- **Not a web app** — Purely terminal-based.
- **No async ORM** — Uses Django's synchronous ORM (Textual workers can wrap blocking calls).

## 7. Roadmap

| Phase | Milestone | Target |
|-------|-----------|--------|
| P0 | Shell + auto-import + table view | v0.1.0 |
| P1 | Detail view + edit + compare | v0.2.0 |
| P2 | Admin links + command browser | v0.3.0 |
| P3 | ptpython integration, theming, plugin system | v0.4.0 |

