PromptVault/SPECS.md

# PromptVault — Application Specification

> **Status:** COMPLETE (source of truth for this application)
> **Last updated:** 2026-10-26

## 1. Overview

PromptVault is a **local-first prompt library for LLM workflows**. It lets a
developer store, organize, search, and reuse reusable prompt templates, with
`{{variable}}` placeholders that can be filled in and rendered on demand.
Everything runs locally: PHP + SQLite on the backend, Vue 3 SPA on the front
end. No accounts, no cloud, no external LLM calls.

### 1.1 Goals
- CRUD for prompts with name, description, body, and tags.
- Extract `{{variables}}` from a prompt body; render the prompt with provided
  values; strict about missing values.
- Search (full-text-ish substring), filter by tag and by favorite, sort by a
  whitelisted set of fields, pagination.
- Track per-prompt usage (`usage_count`, `last_used_at`) incremented whenever a
  prompt is rendered.
- Duplicate, favorite-toggle, and delete prompts.
- Fast, keyboard-friendly single-page UI.

### 1.2 Non-goals (v1)
- Authentication / multi-user support (single-user local tool).
- Calling LLM providers; rendering is purely client-side text interpolation.
- Import/export (CSV/JSON), sharing, comments, versioning.
- Soft deletes, audit logs, i18n.

## 2. Tech stack (decided)

| Layer      | Choice                                                        | Notes |
|------------|---------------------------------------------------------------|-------|
| Language   | PHP **8.4** (min 8.3)                                          | |
| Framework  | **Laravel** (current stable, 12.x/13.x skeleton)              | Slim skeleton, `bootstrap/app.php` wiring |
| ORM        | **Eloquent**                                                  | |
| Database   | **SQLite 3** (`pdo_sqlite`), `database/database.sqlite`       | Laravel's default |
| Frontend   | **Vue 3.5** (`<script setup>`) + **Inertia.js 3** (`@inertiajs/vue3`) | SPA served by Laravel |
| Bundler    | **Vite 8** + `laravel-vite-plugin`                            | |
| Styling    | **Tailwind CSS 4** (`@tailwindcss/vite`)                      | No component libraries |
| PHP tests  | **PHPUnit 12** (shipped with skeleton) + **Xdebug** for coverage | `RefreshDatabase` |
| JS tests   | **Vitest 5** + `@vue/test-utils` + **happy-dom**              | v8 coverage provider |
| HTTP client (JS) | `axios` (skeleton default, used by Inertia)             | |

All versions are "latest stable at scaffold time"; the exact resolved versions
live in `composer.json` / `package.json` (vendor & node_modules excluded from
coverage, per guidelines).

## 3. Architecture

**Principles:** SOLID, KISS, CQRS-lite (separate command/write models from
query/read models), Law of Demeter (each object talks only to its immediate
neighbors: Controller → Service/Request → Model; Vue component → its own props
→ Inertia).

### 3.1 CQRS-lite layout

Writes go through **command DTOs** handled by `PromptService`; reads go through
**query DTOs** handled by `PromptCatalog`. Single-entity actions (delete,
duplicate, favorite, usage) take the model directly — KISS over ceremony.

```
app/
  Actions/Prompts/
    StorePrompt.php          # command DTO: name, description, body, tags[]
    UpdatePrompt.php         # command DTO: same shape, applied to a Prompt
    ListPrompts.php          # query DTO: search, tag, favorites, sort, direction
  Services/
    PromptService.php        # store, update, delete, duplicate, toggleFavorite, recordUsage
    PromptCatalog.php        # list(ListPrompts) -> LengthAwarePaginator; get(id) -> Prompt
    PromptRenderer.php       # pure: extractVariables(), render() (strict)
  Exceptions/
    PromptRenderException.php# carries missingVariables[]
  Http/
    Controllers/PromptController.php  # thin: bind request -> DTO -> service/catalog
    Requests/
      StorePromptRequest.php
      UpdatePromptRequest.php
  Models/
    Prompt.php               # belongsToMany Tag
    Tag.php                  # belongsToMany Prompt
    User.php                 # skeleton default, unused (kept for parity)
database/
  migrations/…_create_tags_table.php
  migrations/…_create_prompts_table.php   # prompts + prompt_tag pivot
  seeders/PromptSeeder.php   # demo tags + 4 sample prompts
  seeders/DatabaseSeeder.php # calls PromptSeeder
resources/js/
  app.js                     # entry wiring (excluded from coverage: wiring only)
  Layouts/AppLayout.vue      # shell, nav
  Pages/Prompts/Index.vue    # table + search/filter/sort + pagination + row actions
  Pages/Prompts/Create.vue   # PromptForm -> POST
  Pages/Prompts/Edit.vue     # PromptForm -> PUT
  Pages/Prompts/Show.vue     # details, RenderPreview, usage stats
  Components/
    PromptForm.vue           # shared create/edit form
    RenderPreview.vue        # variable inputs + live rendered preview
    ConfirmDialog.vue        # confirm-before-danger
    TagPill.vue              # tag chip (clickable in filter contexts)
tests/
  Unit/                      # renderer, models
  Feature/                   # every route, happy + sad paths
  js/                        # Vitest: components + pages (Inertia mocked)
```

### 3.2 Dependency direction
`routes/web.php` → `PromptController` → (`StorePromptRequest` | DTO) →
`PromptService` / `PromptCatalog` → Eloquent models → SQLite.
No model calls a service; no controller touches the DB directly; the renderer
is a pure function with zero framework imports (SRP/DIP-friendly, trivially
unit-testable).

## 4. Data model

```sql
CREATE TABLE tags (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL UNIQUE,           -- max 40, normalized lowercase/trimmed
  created_at TEXT, updated_at TEXT
);

CREATE TABLE prompts (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL,                  -- max 120
  description TEXT,                    -- max 500, nullable
  body TEXT NOT NULL,                  -- prompt template, may contain {{vars}}
  is_favorite INTEGER NOT NULL DEFAULT 0,
  usage_count INTEGER NOT NULL DEFAULT 0,
  last_used_at TEXT,                   -- nullable timestamp
  created_at TEXT, updated_at TEXT
);

CREATE TABLE prompt_tag (
  prompt_id INTEGER NOT NULL REFERENCES prompts(id) ON DELETE CASCADE,
  tag_id    INTEGER NOT NULL REFERENCES tags(id)    ON DELETE CASCADE,
  PRIMARY KEY (prompt_id, tag_id)
);
```

Eloquent casts: `is_favorite => boolean`, `usage_count => integer`,
`last_used_at => datetime`. `tags()` is `belongsToMany` with alphabetical
ordering.

## 5. HTTP surface

All pages are Inertia (HTML); `/use` is JSON. No auth middleware.

| Method | Route                          | Page/JSON | Behavior |
|--------|--------------------------------|-----------|----------|
| GET    | `/`                            | redirect  | 302 → `/prompts` |
| GET    | `/prompts`                     | Index     | List with `search`, `tag`, `favorites`, `sort`, `direction`, `page` query params |
| GET    | `/prompts/create`              | Create    | Empty form |
| POST   | `/prompts`                     | redirect  | Validate → `PromptService::store` → redirect to new prompt |
| GET    | `/prompts/{prompt}`            | Show      | Prompt + extracted variables; 404 if missing |
| GET    | `/prompts/{prompt}/edit`       | Edit      | Form pre-filled |
| PUT    | `/prompts/{prompt}`            | redirect  | Validate → `update` → redirect back to show |
| DELETE | `/prompts/{prompt}`            | redirect  | Delete → redirect to index |
| POST   | `/prompts/{prompt}/duplicate`  | redirect  | Copy → redirect to new prompt |
| POST   | `/prompts/{prompt}/toggle-favorite` | redirect | Flip `is_favorite` → redirect back |
| POST   | `/prompts/{prompt}/use`        | **JSON**  | Body `{"values":{"var":"…"}}` → `{"rendered":"…"}`; on missing vars → `422 {"message":"Missing variables","missing":[…]}`; on success increments usage |

### 5.1 Query param contract (`GET /prompts`)
- `search` — substring match (case-insensitive) across `name`, `description`, `body`.
- `tag` — tag **name**; unknown tag ⇒ empty result set (no error).
- `favorites` — `"1"` ⇒ only favorites.
- `sort` — whitelist: `created_at` (default), `name`, `usage_count`, `last_used_at`, `updated_at`. Anything else ⇒ `created_at`.
- `direction` — `asc` | `desc` (default `desc`; `name` sorts `asc` by default).
- `page` — 1-based; **10 per page**.
- `last_used_at` with `asc`/`desc` keeps `NULL`s last via
  `orderByNulls`-equivalent (`whereNotNull`-aware ordering).

### 5.2 Validation rules
| Field         | Store | Update |
|---------------|-------|--------|
| `name`        | required, string, max:120 | required, string, max:120 |
| `description` | nullable, string, max:500 | nullable, string, max:500 |
| `body`        | required, string          | required, string |
| `tags`        | nullable, array; each: string, max:40 | nullable, array; each: string, max:40 |

> `tags.*` entries: non-strings are rejected (validation); empty / whitespace-only
> strings are **accepted** and stripped during normalization (Laravel's `string`
> rule would wrongly reject them — see decision log #14).

Tag normalization: trim → strip empty → lowercase → unique → create-or-reuse by
name → `sync`.

## 6. Prompt renderer semantics (decided)

- Variable syntax: `{{ name }}` — regex `/\{\{\s*([A-Za-z0-9_-]+)\s*\}\}/`.
  Anything else (`{{}}`, `{{a b}}`, `{{a!b}}`) is **literal text**, not a variable.
- `extractVariables(string $body): string[]` — unique, first-occurrence order.
- `render(string $body, array $values): string` — replaces every occurrence.
  **Strict mode:** if any variable lacks a string value (missing, or non-string
  value), throws `PromptRenderException` with the full ordered list of missing
  variable names. Unknown/extra values in `$values` are ignored.
- Values are inserted verbatim (no escaping; this is plain-text templating, not
  HTML generation).

## 7. Service behavior (decided)

- `store(StorePrompt): Prompt` — insert + sync tags.
- `update(UpdatePrompt, Prompt): Prompt` — set fields + sync tags; usage stats
  untouched.
- `delete(Prompt): void` — hard delete (pivot cascades).
- `duplicate(Prompt): Prompt` — new row: `name = "{name} (copy)"` (appending
  ` (copy)` repeatedly until unique, e.g. `"X (copy) (copy)"`), same
  description/body/tags, `is_favorite = false`, `usage_count = 0`,
  `last_used_at = null`.
- `toggleFavorite(Prompt): Prompt` — flip boolean.
- `recordUsage(Prompt): Prompt` — `usage_count += 1`, `last_used_at = now`.
- `PromptCatalog::list(ListPrompts)` — applies §5.1, eager-loads `tags`,
  paginates 10.
- Single-prompt reads (show/edit/use) use route model binding + `loadMissing('tags')`; no separate `PromptCatalog::get()` (decision #15).

## 8. Frontend decisions

- **Inertia 2 + Vue 3 `<script setup>`**; no Pinia (prop-driven pages, KISS).
- **AppLayout**: top bar with brand "PromptVault", nav (Prompts, + New
  Prompt), max-width container.
- **Index**: search input (debounced, updates `?search`), tag dropdown (from
  `tags` prop), favorites toggle, sort/direction select, table
  (Name / Tags / Usage / Last used / Favorite star), row actions: Show,
  Duplicate, Favorite, Delete (ConfirmDialog). Pagination prev/next.
- **Show**: metadata, tags, body in `<pre>`, variable list, **RenderPreview**
  (one input per variable + live preview + "Copy rendered" button + "Use
  prompt" button that POSTs values and shows the rendered result and bumps
  usage), danger zone (Duplicate / Delete).
- **Create/Edit**: shared **PromptForm** (name, description, body, tag input
  with comma separation + suggestion chips), server error display, submit via
  Inertia `useForm`.
- **RenderPreview** computes the preview client-side using the same regex
  rules as the server (documented as a mirrored contract).
- Styling: Tailwind utility classes only; dark-agnostic neutral palette; no
  external fonts/icons (unicode glyphs only, e.g. ★ ✎ 🗑 — keep it dependency-free).

## 9. Testing strategy (decided)

Target: **≥ 95% line coverage of application code** with:
- PHP: `app/**` (PHPUnit 12 + Xdebug).
- JS: `resources/js/**` (Vitest 5 + v8 provider), **excluding** `app.js`
  (framework wiring with no logic — disclosed exclusion).
- `vendor/` and `node_modules/` excluded per guidelines (they never are).

PHP suites (PHPUnit 12; `inertiajs/inertia-laravel` 3 ships the built-in
`assertInertia` macro, no extra package needed):
- `Unit/PromptRendererTest.php` — extraction edge cases (none, repeats,
  spacing, invalid tokens, order), render success, strict missing, extra
  values ignored, verbatim insertion.
- `Unit/ListPromptsTest.php` — sort/direction normalization + fallbacks.
- `Unit/ModelsTest.php` — Prompt/Tag relations, casts, tag ordering, User
  smoke (skeleton model).
- `Feature/HomeTest.php` — `GET /` → 302 → `/prompts`.
- `Feature/Prompts/PromptIndexTest.php` — default list, search, tag filter
  (known + unknown), favorites, each sort + direction, `last_used_at`
  NULLs-last in both directions, invalid sort/direction fallback, pagination
  size.
- `Feature/Prompts/PromptStoreUpdateTest.php` — create page render (empty
  form + suggested tags; old-input reflash after failed store), valid store
  (incl. tag normalization/create/reuse), each invalid case, valid update,
  invalid update, tag sync on update (add + remove).
- `Feature/Prompts/PromptShowDeleteTest.php` — show found/404, edit page,
  delete/404.
- `Feature/Prompts/PromptActionsTest.php` — duplicate (copy name, tag copy,
  unique-name collision, stats reset), toggle favorite (on↔off), `use`
  success (payload rendered, counters updated), `use` missing variables
  (422 + `missing[]`), `use` non-string value (422), `use` with no `values`
  (validation 422), `use` 404.

JS suites (`tests/js/` — 64 tests across 10 files, all green; Inertia mocked
with a shared stub, `tests/js/stubs/inertia.js`: `Link`, `Head`, `router`,
`useForm`, `usePage`, plus `inertiaMock` helpers `failNext` (rejected
submission: seeds `form.errors` + `page.props.errors`, fires `onError`) and
`deferSubmissions` (assert `processing === true` states); `resources/js/app.js`
entry wiring excluded from coverage, disclosed):
- `lib/format.test.js` — empty → em-dash, invalid → raw pass-through,
  valid → localized format.
- `Components/TagPill.test.js` — plain span vs. filterable Inertia link
  (encoded filter href).
- `Components/ConfirmDialog.test.js` — render states, confirm/cancel emits,
  Escape key handling, listener attach/detach.
- `Components/PromptForm.test.js` — field render, tag chip add/remove
  (Enter/comma/Backspace/blur), duplicate/empty rejection, suggestion chips,
  server-error display (array + string), POST/PUT payload transform,
  processing state, `onError`/`clearErrors`, cancel link.
- `Components/RenderPreview.test.js` — variable input generation, live preview
  substitution, empty-state, `use` emit with entered values, busy state,
  clipboard copy success/failure.
- `Layouts/AppLayout.test.js` — brand/nav/footer + slot render.
- `Pages/Prompts/Index.test.js` — rows from props, empty state, search/submit
  form, tag/favorites/sort/direction filters, favorite & duplicate actions,
  delete confirm + cancel (+ no-target guard), pagination incl. boundaries.
- `Pages/Prompts/Show.test.js` — renders prompt + variables, favorite/duplicate
  /delete flows, copy template (success/failure), "use" flow success, 422 with
  `missing[]` list, unreadable error body, network failure.
- `Pages/Prompts/Create.test.js` / `Pages/Prompts/Edit.test.js` — form wiring
  (titles, labels, hrefs) + submit URLs.

## 10. Conventions

- Controllers stay < ~40 lines per action: validate → map to DTO → service →
  respond. No business logic in controllers, requests, or models.
- No `dd()`/`dump()` in committed code; no TODOs left in code.
- Migrations are forward-only; seeders are idempotent (delete-then-seed demo
  data).
- All new behavior lands in SPECS.md **before** code (this file is the source
  of truth).
- Commits/batches: code written in batches of ≤ 5 files per pass.

## 11. Decision log

| # | Date        | Decision |
|---|------------|----------|
| 1 | 2026-10-24 | Build PromptVault (local-first LLM prompt library) as the application. |
| 2 | 2026-10-24 | Stack: Laravel (latest) + SQLite + Vue 3 + Inertia + Vite + Tailwind 4; PHPUnit + Vitest. |
| 3 | 2026-10-24 | CQRS-lite: command/query DTOs + `PromptService`/`PromptCatalog`; pure `PromptRenderer`. |
| 4 | 2026-10-24 | No auth in v1; hard deletes; usage counted on render (`/use`). |
| 5 | 2026-10-24 | Strict variable rendering; variable charset `[A-Za-z0-9_-]+`. |
| 6 | 2026-10-24 | ≥ 95% coverage of `app/` + `resources/js/` (entry wiring files excluded, disclosed). |
| 7 | 2026-10-24 | 10 items/page pagination; sort whitelist; tag names normalized lowercase. |
| 8 | 2026-10-24 | Skeleton resolved to Laravel 13 + PHPUnit 12 (skeleton default, kept over Pest) + Vite 8. |
| 9 | 2026-10-24 | Resolved deps: `@inertiajs/vue3` 3.x, Vue 3.5, Vitest 5, `inertiajs/inertia-laravel` 3.5. Root view `resources/views/app.blade.php` uses `<inertia:app>` / `<inertia:head>`. |
| 10 | 2026-10-25 | Bug fix: `PromptCatalog::list()` used non-existent `orderByNulls()` (500 on `?sort=last_used_at`); replaced with `orderByRaw('last_used_at IS NULL')` + `orderBy()` so NULLs sort last in either direction (§5.1). |
| 11 | 2026-10-25 | Bug fix: `PromptService::duplicate()` synced tags via `pluck('tags.id','tags.id')` (always null → corrupt pivot insert); now `pluck('id')` (§7). |
| 12 | 2026-10-25 | JS coverage needs `@vitest/coverage-v8` (installed as devDependency); `npm run test:js` / `test:js:coverage` scripts added. |
| 13 | 2026-10-25 | `duplicate()` reworked: `$model->replicate(['name','description','body'])` misused Laravel's `$except` semantics (those attributes were *removed* → NOT NULL violation on `body`); replaced with an explicit `Prompt::create()` + tag `sync` (KISS, matches `store`/`update` shape; stats reset via column defaults) (§7). |
| 14 | 2026-10-25 | `tags.*` validation changed from `['string','max:40']` to an `is_string` closure + `max:40`: the `string` rule (via `FILTER_VALIDATE_STRING`) rejects empty/whitespace-only entries, contradicting the §5.2 contract that such entries are stripped during normalization. Laravel's global `TrimStrings` + `ConvertEmptyStringsToNull` middleware rewrite empty/whitespace entries to `null` before validation, so the closure accepts `null` (stripped in `tagIds`); other non-strings are rejected (§5.2). |
| 15 | 2026-10-25 | Removed unused `PromptCatalog::get()` (single-prompt reads use route model binding + `loadMissing('tags')` — KISS, no dead API, §7); added create-page tests covering `PromptController::create()` (empty form + suggested tags; old-input reflash). Only remaining uncovered PHP lines: two defensive `preg_*`-failure guards in `PromptRenderer` (unreachable with a valid static pattern; deliberate fail-loud contract). |
| 16 | 2026-10-26 | Bug fix (caught by the new JS tests): `RenderPreview.vue`'s Use button ran `@click="emit('use', { ...values.value })"` in the template, where the top-level `values` ref is auto-unwrapped — so it spread `undefined` and always emitted `{}`, making the real UI's `/use` flow always 422 ("missing variables"). Moved the emit into a script-scope `emitUse()` method bound via `@click="emitUse"`; the button now emits the actually entered values (§8). |
| 17 | 2026-10-26 | JS test harness complete (fulfilling #12): 64 Vitest tests / 10 files under `tests/js/` with the shared Inertia stub + helpers, all green. Coverage of `resources/js/` (excl. disclosed `app.js` entry wiring): **100% lines / 99.57% statements / 96.31% branches / 98.82% functions** — ≥ 95% on every metric. Combined with PHP (60 tests, 99.05% lines), the ≥ 95% application-code coverage requirement (§9) is met for `app/` + `resources/js/`. |