its-magic 0.1.2-9 → 0.1.2

package/sprints/S0001/qa-findings.md

@@ -1,113 +0,0 @@
-# QA Findings — Webview UI → Backend Integration & Invalid Input Handling
-
-**Sprint:** S0001
-**Date:** 2026-02-06
-**Scope:** Verify the webview UI calls the backend correctly and handles invalid input.
-**Method:** Static code review of `examples/webview-app/` (frontend + backend + shared schema).
-
----
-
-## Test Plan
-
-### Area 1 — UI → Backend API Calls
-
-| # | Test Case | Frontend Entry Point | API Endpoint | Result |
-|---|-----------|---------------------|-------------|--------|
-| 1 | Initial page load fetches items | `loadItems()` on bootstrap (line 338) | `GET /api/v1/items` | PASS |
-| 2 | Filter change reloads items | `change` listeners → `loadItems()` (lines 301-304) | `GET /api/v1/items?status=…&category=…` | PASS |
-| 3 | Search input debounced reload | `input` → 300ms debounce → `loadItems()` (lines 305-308) | `GET /api/v1/items?search=…` | PASS |
-| 4 | Pagination prev/next | Button clicks update `currentMeta.page` → `loadItems()` (lines 315-320) | `GET /api/v1/items?page=N` | PASS |
-| 5 | Click item opens detail | `openDetail()` → `fetchItem(id)` (lines 215-230) | `GET /api/v1/items/:id` | PASS |
-| 6 | Delete item calls API | `handleDelete()` → `deleteItem(id)` (lines 263-275) | `DELETE /api/v1/items/:id` | PASS |
-| 7 | Clear/reset filters resets & reloads | `clearFilters()` → `loadItems()` (lines 252-259) | `GET /api/v1/items` (defaults) | PASS |
-| 8 | Keyboard nav (arrows) opens detail | `navigateItem()` → `openDetail()` (lines 329-334) | `GET /api/v1/items/:id` | PASS |
-| 9 | Request headers set Content-Type JSON | `apiFetch()` sets `Content-Type: application/json` (line 52) | All endpoints | PASS |
-| 10 | 204 response handled (delete) | `apiFetch()` returns null on 204 (line 56) | `DELETE /api/v1/items/:id` | PASS |
-
-### Area 2 — Invalid Input Handling
-
-| # | Test Case | Frontend Behaviour | Backend Behaviour | Result |
-|---|-----------|--------------------|--------------------|--------|
-| 11 | API returns 400 validation error | `apiFetch()` throws structured Error with code/details (lines 60-64) | 400 + `VALIDATION_ERROR` envelope | PASS |
-| 12 | List load failure shows error in UI | `loadItems()` catch renders `.error-message` div (lines 208-211) | N/A | PASS |
-| 13 | Detail load failure feedback | `openDetail()` catch logs to console only (lines 227-229) | 404 `NOT_FOUND` | **FAIL** |
-| 14 | Delete failure shows alert | `handleDelete()` catch calls `alert()` (lines 272-274) | 404/400 | PASS |
-| 15 | Search maxlength enforced client-side | `<input maxlength="200">` (index.html line 50) | `validateQuery` checks ≤200 (validators.js line 149) | PASS |
-| 16 | XSS prevention | `escapeHtml()` used for title/category rendering (lines 143, 147) | N/A | PASS |
-| 17 | Invalid status in query params | Backend rejects with 400 | `validateQuery` checks enum (validators.js lines 137-146) | PASS |
-| 18 | Invalid sort/order params | Backend rejects with 400 | `validateQuery` checks enum (validators.js lines 167-171) | PASS |
-| 19 | Invalid page/pageSize params | Backend rejects with 400 | `validateQuery` checks integer + range (validators.js lines 159-164) | PASS |
-| 20 | Non-JSON backend response | `res.json()` throws SyntaxError — unhandled gracefully | N/A | **FAIL** |
-| 21 | Category filter not validated by backend | Unrecognized category returns empty list (no error) | No category enum validation in `validateQuery` | **WARN** |
-| 22 | POST/PATCH body validation (title required) | N/A (no create/edit UI) | `validateBody` enforces required + length (validators.js lines 82-124) | PASS |
-
----
-
-## Findings
-
-### F-001 — Silent failure on item detail fetch (Medium)
-
-**File:** `examples/webview-app/frontend/app.js` lines 224-229
-**Severity:** Medium
-**Category:** UX / Error handling
-
-`openDetail()` catches fetch errors but only logs to `console.error`. The user receives no visible feedback when a detail fetch fails (e.g., item deleted by another user, network error). Compare with `loadItems()` which renders an inline error message, and `handleDelete()` which shows an `alert()`.
-
-**Expected:** Display a user-visible error in the detail panel or a toast notification.
-**Recommendation:** Render an error state inside `$detailPanel` or show an inline banner, consistent with the error handling in `loadItems()`.
-
----
-
-### F-002 — Non-JSON error responses crash `apiFetch` (Medium)
-
-**File:** `examples/webview-app/frontend/app.js` lines 49-68
-**Severity:** Medium
-**Category:** Robustness
-
-`apiFetch()` unconditionally calls `res.json()` for all non-204 responses (line 58). If the backend returns a non-JSON response (e.g., an HTML proxy error page, a 502 from a reverse proxy, or a plain-text 500), `res.json()` will throw a `SyntaxError` instead of the structured error the callers expect.
-
-**Expected:** Graceful handling of non-JSON responses with a fallback error message.
-**Recommendation:** Wrap `res.json()` in a try/catch or check the `Content-Type` header before parsing.
-
----
-
-### F-003 — No loading/spinner state during API calls (Low)
-
-**File:** `examples/webview-app/frontend/app.js`
-**Severity:** Low
-**Category:** UX
-
-No loading indicator is shown during any API call (`loadItems`, `openDetail`, `handleDelete`). On slow connections or when the backend is unresponsive, the UI appears frozen with no feedback.
-
-**Expected:** A spinner or skeleton state while data is loading.
-
----
-
-### F-004 — Category filter values not validated on backend (Low)
-
-**File:** `examples/webview-app/backend/validators.js` lines 132-185
-**Severity:** Low
-**Category:** Validation gap
-
-`validateQuery` validates `status` against the schema enum but does not validate the `category` query parameter against any allow-list. An arbitrary category value like `?category=XSS_ATTEMPT` would simply produce an empty result set (no crash), so this is low-severity. However, it is inconsistent with the `status` validation approach.
-
----
-
-### F-005 — Soft-delete confirmation implies restorability but no restore UI exists (Low)
-
-**File:** `examples/webview-app/frontend/app.js` line 265
-**Severity:** Low
-**Category:** UX
-
-The delete confirmation says _"This action is reversible (soft delete)"_, which is technically true at the data layer. However, no UI exists to undelete items, making this effectively irreversible from the user's perspective.
-
----
-
-## Verdict
-
-| Severity | Count |
-|----------|-------|
-| Medium   | 2 (F-001, F-002) |
-| Low      | 3 (F-003, F-004, F-005) |
-
-**Overall:** The UI correctly calls all documented backend endpoints. Filter, search, pagination, detail, and delete flows all route to the correct API paths with proper parameters. Backend validation is solid with structured error envelopes. Two medium-severity gaps exist in frontend error handling that should be addressed before release: silent detail fetch failures (F-001) and non-JSON response handling (F-002). No critical/blocking defects found.

package/sprints/S0001/sprint.md

@@ -1,70 +0,0 @@
-# Sprint S0001
-
-## Goal
-
-Deliver a working vertical slice: filtered item list with detail panel, powered by a shared-schema REST API. Users can filter items by status/category/date, view details in a slide-over panel, and create/update items — all validated end-to-end with shared Zod schemas.
-
-## Scope
-
-- **US-0002** — Filter Bar with Instant Results
-- **US-0003** — Slide-Over Detail Panel
-- **US-0004** — Empty-State & Filter Awareness
-
-## User Stories → Task Mapping
-
-| Story   | Tasks                          |
-|---------|--------------------------------|
-| US-0002 | T-015, T-016, T-017, T-018, T-019 |
-| US-0003 | T-010, T-016, T-020           |
-| US-0004 | T-021                          |
-| Infra   | T-001, T-002, T-003, T-007, T-008, T-022 |
-
-## Build Order (dependency chain)
-
-```
-T-001 Scaffold workspace
-  └─ T-002 Shared Zod schemas + types
-      ├─ T-003 tsconfig path aliases
-      ├─ T-004 Backend validation middleware
-      └─ T-005 Frontend form validation setup
-          │
-  T-007 Express server + health check ─┐
-  T-008 Drizzle schema + SQLite setup ──┤
-  T-014 Error envelope ────────────────┘
-          │
-  T-009 GET /items (filtered + paginated)
-  T-010 GET /items/:id
-  T-011 POST /items
-  T-012 PATCH /items/:id
-  T-013 DELETE /items/:id (soft)
-          │
-  T-015 React + Vite + Tailwind shell ─┐
-  T-022 Vite dev proxy ────────────────┘
-          │
-  T-016 Typed API client + TanStack Query hooks
-  T-006 Response validation on API client
-          │
-  T-017 FilterBar component
-  T-018 useFilters hook (URL sync)
-  T-019 ItemList component
-  T-020 DetailPanel component
-  T-021 EmptyState component
-```
-
-## Risks
-
-| Risk | Likelihood | Impact | Mitigation |
-|------|-----------|--------|------------|
-| Shared schema drift if `/shared` is not built first | Medium | High | npm workspaces build order: shared → backend → frontend |
-| CORS misconfiguration between SPA and API | Medium | Low | Vite proxy for dev; explicit CORS middleware for prod |
-| SQLite → PostgreSQL dialect differences | Low | Medium | Drizzle ORM abstracts dialect; test against both in CI |
-| Filter query params exceed URL length | Low | Low | Start with 4 dimensions; add POST filter fallback if needed |
-
-## Definition of Done
-
-- All 22 tasks complete and checked off in `tasks.md`
-- Shared schemas consumed by both frontend and backend without duplication
-- API returns structured error envelope for validation failures
-- Filter bar updates list instantly; active filters reflected in URL
-- Detail panel opens/closes with keyboard navigation (arrows, Escape)
-- Empty state renders with "Reset filters" action when no results match

package/sprints/S0001/summary.md

@@ -1,46 +0,0 @@
-# Sprint Summary — S0001
-
-## Goal
-
-Deliver a working vertical slice: filtered item list with detail panel, powered by a shared-schema REST API.
-
-## Completed
-
-- GSD Workflow Kit: all slash commands, agent roles, rules, templates, and CI/CD workflows
-- Installers (PowerShell, Bash, Python) for kit distribution
-- Benchmark harness (scenario, live, headless, prompted modes)
-- Reference app (`examples/webview-app/`):
-  - Express backend with full CRUD API (`/api/v1/items`)
-  - Shared JSON Schema for cross-layer validation
-  - Structured error envelopes (VALIDATION_ERROR, NOT_FOUND, INTERNAL_ERROR)
-  - Frontend SPA with filter bar, sortable list, pagination
-  - Slide-over detail panel with keyboard navigation
-  - Empty state with filter awareness and reset action
-  - XSS prevention, soft-delete, seed data (20 items)
-- Architecture decisions documented (DEC-0001, DEC-0002)
-- QA review completed — 22 test cases, 20 PASS, 2 FAIL, 1 WARN
-
-## User Stories Delivered
-
-| Story   | Title                          | Status    |
-|---------|--------------------------------|-----------|
-| US-0002 | Filter Bar with Instant Results | Delivered |
-| US-0003 | Slide-Over Detail Panel         | Delivered |
-| US-0004 | Empty-State & Filter Awareness  | Delivered |
-
-## Open Items
-
-- **F-001** (Medium): Silent failure on item detail fetch — needs visible user feedback
-- **F-002** (Medium): Non-JSON error responses crash `apiFetch` — needs try/catch or Content-Type check
-- **F-003** (Low): No loading/spinner state during API calls
-- **F-004** (Low): Category filter values not validated on backend
-- **F-005** (Low): Soft-delete confirmation implies restorability but no restore UI exists
-
-## Metrics
-
-- QA test cases: 22
-- Pass: 20 | Fail: 2 | Warn: 1
-- Critical/blocking defects: 0
-- Medium findings: 2
-- Low findings: 3
-

package/sprints/S0001/tasks.md

@@ -1,35 +0,0 @@
-# Tasks — Sprint S0001
-
-## Shared Schema
-
-- [ ] **T-001** Scaffold npm workspace with `frontend/`, `backend/`, `shared/` packages and root `package.json` with workspaces config
-- [ ] **T-002** Create shared Zod schemas: `shared/schemas/item.schema.ts` (CreateItemSchema, UpdateItemSchema, ItemStatus enum) and `shared/schemas/filter.schema.ts` (ItemFilterSchema with pagination, sort, date range); export inferred TypeScript types from `shared/types/`
-- [ ] **T-003** Configure `tsconfig.base.json` with path aliases (`@shared/*`) and per-package tsconfig files extending it
-
-## Validation
-
-- [ ] **T-004** Implement backend validation middleware (`backend/src/middleware/validate.ts`) — generic Zod safeParse for body, query, and params; returns 400 with structured error details on failure
-- [ ] **T-005** Configure frontend form validation with `@hookform/resolvers/zod` using shared CreateItemSchema and UpdateItemSchema
-- [ ] **T-006** Add response validation on frontend API client — parse API responses through shared Zod schemas to catch contract drift at runtime
-
-## API
-
-- [ ] **T-007** Stand up Express 5 server (`backend/src/server.ts`) with health check endpoint (`GET /api/v1/health`), CORS middleware, JSON body parser, and global error handler
-- [ ] **T-008** Create Drizzle ORM schema (`backend/src/db/schema.ts`) with items table (id, title, status, category, description, metadata, createdAt, updatedAt, deletedAt) and SQLite connection for dev
-- [ ] **T-009** Implement `GET /api/v1/items` — filtered list with status, category, dateFrom/dateTo, search, pagination (page/pageSize), sort, and order; uses validate middleware with ItemFilterSchema; returns data array + meta object
-- [ ] **T-010** Implement `GET /api/v1/items/:id` — single item with full details; returns 404 with error envelope if not found
-- [ ] **T-011** Implement `POST /api/v1/items` — create item; validates body with CreateItemSchema; returns 201 with created item
-- [ ] **T-012** Implement `PATCH /api/v1/items/:id` — partial update; validates body with UpdateItemSchema; returns updated item or 404
-- [ ] **T-013** Implement `DELETE /api/v1/items/:id` — soft delete (set deletedAt); returns 204 No Content or 404
-- [ ] **T-014** Implement structured error envelope middleware — consistent `{ error: { code, message, details } }` shape for VALIDATION_ERROR, NOT_FOUND, and INTERNAL_ERROR
-
-## UI
-
-- [ ] **T-015** Scaffold React 18 + Vite + TypeScript app in `frontend/`; install and configure Tailwind CSS, React Router v6 with a root layout route
-- [ ] **T-016** Create typed API client (`frontend/src/api/client.ts`) and TanStack Query hooks (`useItems`, `useItem`, `useCreateItem`, `useUpdateItem`, `useDeleteItem`) wrapping all endpoints
-- [ ] **T-017** Build `FilterBar` component — horizontal chip-based multi-select for status, category, and date range (US-0002); active filters shown as filled chips with "x" dismiss; "Clear all" link when 2+ filters active
-- [ ] **T-018** Build `useFilters` hook — reads/writes filter state to URL search params via React Router `useSearchParams`; provides `setFilter`, `removeFilter`, `clearAll`, and `activeFilterCount`
-- [ ] **T-019** Build `ItemList` component — renders filtered items in a scrollable list; supports keyboard navigation (arrow keys to move focus); preserves scroll position when detail panel is open
-- [ ] **T-020** Build `DetailPanel` component — slide-over panel from the right showing full item details, metadata, and action buttons (edit, delete, status change); arrow keys for next/prev item; Escape to close (US-0003)
-- [ ] **T-021** Build `EmptyState` component — friendly illustration/message when filters return zero results; one-click "Reset filters" button; active filter count badge on filter bar (US-0004)
-- [ ] **T-022** Configure Vite dev proxy (`vite.config.ts`) to forward `/api` requests from `:5173` to Express on `:3000`

package/sprints/S0001/uat.json

@@ -1,8 +0,0 @@
-{
-  "sprint": "S0001",
-  "steps": [],
-  "summary": {
-    "passed": 0,
-    "failed": 0
-  }
-}

package/sprints/S0001/uat.md

@@ -1,8 +0,0 @@
-# UAT
-
-## Steps
-- ...
-
-## Results
-- ...
-

package/sprints/quick/Q0001/summary.md

@@ -1,3 +0,0 @@
-# Quick Task Summary
-
-- ...