its-magic 0.1.2-9 → 0.1.3-0

package/scripts/release-all.ps1

@@ -1,423 +0,0 @@
-<#
-.SYNOPSIS
-  Unified release: npm + Chocolatey + Homebrew (all three at once).
-.DESCRIPTION
-  1. Bumps version in package.json (patch|minor|major|explicit)
-  2. Publishes to npm
-  3. Creates a GitHub release with a source zip (for Homebrew/Chocolatey URLs)
-  4. Updates Chocolatey nuspec + pushes to chocolatey.org
-  5. Updates Homebrew formula with new URL + sha256
-.PARAMETER Bump
-  Version bump type: patch, minor, major, or an explicit semver (e.g. 1.2.3).
-  Default: patch
-.PARAMETER NpmTag
-  npm dist-tag (e.g. latest, beta, rc). Default: latest
-.PARAMETER SkipNpm
-  Skip npm publish.
-.PARAMETER SkipChoco
-  Skip Chocolatey push.
-.PARAMETER SkipBrew
-  Skip Homebrew formula update.
-.PARAMETER DryRun
-  Print what would happen without executing.
-#>
-param(
-    [string]$Bump = "patch",
-    [string]$NpmTag = "latest",
-    [switch]$SkipNpm,
-    [switch]$SkipChoco,
-    [switch]$SkipBrew,
-    [switch]$DryRun,
-    [switch]$SkipBrewPush,
-    [string]$BrewTapRepo = "",
-    [string]$BrewTapBranch = "main",
-    [string]$BrewTapDir = "",
-    [bool]$CreateBrewTapIfMissing = $true
-)
-
-$ErrorActionPreference = 'Stop'
-$repoRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
-if (-not (Test-Path (Join-Path $repoRoot 'package.json'))) {
-    $repoRoot = Split-Path -Parent $PSScriptRoot
-}
-Push-Location $repoRoot
-
-# ── Helpers ──────────────────────────────────────────────────────────
-function Log($msg) { Write-Host "[release] $msg" -ForegroundColor Cyan }
-function Warn($msg){ Write-Host "[release] $msg" -ForegroundColor Yellow }
-function Err($msg) { Write-Host "[release] $msg" -ForegroundColor Red; Pop-Location; exit 1 }
-
-# Quote char for building regex patterns (avoids PS 5.1 parser issues)
-$DQ = [char]34
-$chocoFailed = $false
-$brewTapFailed = $false
-$brewTapPushed = $false
-
-# ── 1. Version bump ─────────────────────────────────────────────────
-Log "Bumping version ($Bump) ..."
-if ($DryRun) {
-    Log "(dry-run) would run: npm version $Bump --no-git-tag-version"
-    $newVersion = "0.0.0-dryrun"
-} else {
-    npm version $Bump --no-git-tag-version | Out-Null
-    $pkg = Get-Content package.json -Raw | ConvertFrom-Json
-    $newVersion = $pkg.version
-}
-Log "New version: $newVersion"
-
-# ── 2. npm publish ───────────────────────────────────────────────────
-if (-not $SkipNpm) {
-    Log "Publishing to npm (tag=$NpmTag) ..."
-    if ($DryRun) {
-        Log "(dry-run) would run: npm publish --tag $NpmTag"
-    } else {
-        npm publish --tag $NpmTag
-        if ($LASTEXITCODE -ne 0) { Err "npm publish failed" }
-        Log "npm publish OK"
-    }
-} else {
-    Warn "Skipping npm"
-}
-
-# ── 3. GitHub release (needed by Homebrew + Chocolatey) ──────────────
-$ghAvailable = $null -ne (Get-Command gh -ErrorAction SilentlyContinue)
-$tagName = "v$newVersion"
-$zipUrl  = ""
-$tarUrl  = ""
-
-$isPrerelease = $newVersion -match '-'
-$chocoVersion = $newVersion
-if ($newVersion -match '^(\d+\.\d+\.\d+)-(\d+)$') {
-    # Old Chocolatey/NuGet rejects numeric-only prerelease labels (e.g. 0.1.1-1).
-    # Convert to a compatible label for nuspec only.
-    $chocoVersion = "$($Matches[1])-beta$($Matches[2])"
-}
-if ($chocoVersion -ne $newVersion) {
-    Log "Chocolatey version normalized: $newVersion -> $chocoVersion"
-}
-
-if ($ghAvailable) {
-    Log "Creating GitHub release $tagName ..."
-    if ($DryRun) {
-        Log "(dry-run) would run: gh release create $tagName --generate-notes"
-        $zipUrl = "https://github.com/USER/its-magic/archive/refs/tags/$tagName.zip"
-        $tarUrl = "https://github.com/USER/its-magic/archive/refs/tags/$tagName.tar.gz"
-    } else {
-        $ghArgs = @("release", "create", $tagName, "--generate-notes", "--title", $tagName)
-        if ($isPrerelease) { $ghArgs += "--prerelease" }
-        & gh @ghArgs
-        if ($LASTEXITCODE -ne 0) { Warn "gh release create failed - continuing anyway" }
-        # Derive archive URL from current remote
-        $remoteUrl = git remote get-url origin 2>$null
-        if ($remoteUrl -match 'github\.com[:/](.+?)(\.git)?$') {
-            $repoSlug = $Matches[1]
-            $zipUrl = "https://github.com/$repoSlug/archive/refs/tags/$tagName.zip"
-            $tarUrl = "https://github.com/$repoSlug/archive/refs/tags/$tagName.tar.gz"
-        }
-        Log "GitHub release created: $tagName"
-    }
-} else {
-    Warn "gh CLI not found - skipping GitHub release"
-    $zipUrl = "https://github.com/USER/its-magic/archive/refs/tags/$tagName.zip"
-    $tarUrl = "https://github.com/USER/its-magic/archive/refs/tags/$tagName.tar.gz"
-}
-
-# ── 4. Chocolatey ───────────────────────────────────────────────────
-if (-not $SkipChoco) {
-    $chocoDir = Join-Path $repoRoot 'packaging\chocolatey'
-    $nuspec   = Join-Path $chocoDir 'its-magic.nuspec'
-    $chocoInstall = Join-Path $chocoDir 'tools\chocolateyInstall.ps1'
-
-    if (Test-Path $nuspec) {
-        Log "Updating Chocolatey nuspec to $chocoVersion ..."
-        if (-not $DryRun) {
-            # Update version in nuspec
-            $xml = [xml](Get-Content $nuspec -Raw)
-            $xml.package.metadata.version = $chocoVersion
-            $xml.Save($nuspec)
-
-            # Update URL in install script
-            $installContent = Get-Content $chocoInstall -Raw
-            if ($zipUrl) {
-                $installContent = $installContent -replace "\`$url\s*=\s*'[^']+'", "`$url         = '$zipUrl'"
-            }
-            Set-Content -Path $chocoInstall -Value $installContent
-        }
-
-        # Compute checksum if we have the zip
-        if ($zipUrl -and -not $DryRun) {
-            Log "Downloading zip for checksum ..."
-            $tmpZip = Join-Path $env:TEMP "gsd-$tagName.zip"
-            try {
-                Invoke-WebRequest -Uri $zipUrl -OutFile $tmpZip -UseBasicParsing
-                $sha = (Get-FileHash -Path $tmpZip -Algorithm SHA256).Hash.ToLower()
-                $installContent = Get-Content $chocoInstall -Raw
-                $installContent = $installContent -replace "\`$checksum\s*=\s*'[^']+'", "`$checksum    = '$sha'"
-                Set-Content -Path $chocoInstall -Value $installContent
-                Remove-Item $tmpZip -Force
-                Log "Checksum: $sha"
-            } catch {
-                Warn "Could not download zip for checksum - set PLACEHOLDER manually"
-            }
-        }
-
-        $chocoAvailable = $null -ne (Get-Command choco -ErrorAction SilentlyContinue)
-        if ($chocoAvailable) {
-            Log "Packing + pushing Chocolatey package ..."
-            if ($DryRun) {
-                Log "(dry-run) would run: choco pack + choco push"
-            } else {
-                Push-Location $chocoDir
-                choco pack
-                if ($LASTEXITCODE -ne 0) {
-                    $chocoFailed = $true
-                    Warn "choco pack failed"
-                } else {
-                    $nupkg = Get-ChildItem "*.nupkg" | Sort-Object LastWriteTime -Descending | Select-Object -First 1
-                    if ($nupkg) {
-                        choco push $nupkg.Name --source https://push.chocolatey.org/
-                        if ($LASTEXITCODE -ne 0) {
-                            $chocoFailed = $true
-                            Warn "choco push failed"
-                        }
-                        else { Log "Chocolatey push OK" }
-                    } else {
-                        $chocoFailed = $true
-                        Warn "No .nupkg created by choco pack"
-                    }
-                }
-                Pop-Location
-            }
-        } else {
-            $chocoFailed = $true
-            Warn "choco not found - nuspec updated but not pushed. Run choco pack and choco push manually."
-        }
-    } else {
-        $chocoFailed = $true
-        Warn "nuspec not found at $nuspec - skipping Chocolatey"
-    }
-} else {
-    Warn "Skipping Chocolatey"
-}
-
-# ── 5. Homebrew ─────────────────────────────────────────────────────
-if (-not $SkipBrew) {
-    # Detect pre-release: anything with a hyphen
-    if ($isPrerelease) {
-        $formulaPath = Join-Path $repoRoot 'packaging\homebrew\its-magic-beta.rb'
-        Log "Pre-release detected - using beta formula"
-    } else {
-        $formulaPath = Join-Path $repoRoot 'packaging\homebrew\its-magic.rb'
-    }
-
-    if (Test-Path $formulaPath) {
-        $formulaName = Split-Path -Leaf $formulaPath
-        Log "Updating Homebrew formula ($formulaName) to $newVersion ..."
-        if (-not $DryRun) {
-            $formula = Get-Content $formulaPath -Raw
-
-            # Update version in URL
-            if ($tarUrl) {
-                $urlPattern = 'url ' + $DQ + 'https://github\.com/[^' + $DQ + ']+\.tar\.gz' + $DQ
-                $urlReplace = 'url ' + $DQ + $tarUrl + $DQ
-                $formula = $formula -replace $urlPattern, $urlReplace
-            } else {
-                $formula = $formula -replace 'vVERSION', $tagName
-            }
-
-            # Update explicit version line for beta formula
-            if ($isPrerelease) {
-                $verPattern = 'version ' + $DQ + '[^' + $DQ + ']*' + $DQ
-                $verReplace = 'version ' + $DQ + $newVersion + $DQ
-                $formula = $formula -replace $verPattern, $verReplace
-            }
-
-            # Compute tar.gz sha256 if possible
-            if ($tarUrl) {
-                $tmpTar = Join-Path $env:TEMP "gsd-$tagName.tar.gz"
-                try {
-                    Invoke-WebRequest -Uri $tarUrl -OutFile $tmpTar -UseBasicParsing
-                    $sha = (Get-FileHash -Path $tmpTar -Algorithm SHA256).Hash.ToLower()
-                    $shaPattern = 'sha256 ' + $DQ + '[^' + $DQ + ']*' + $DQ
-                    $shaReplace = 'sha256 ' + $DQ + $sha + $DQ
-                    $formula = $formula -replace $shaPattern, $shaReplace
-                    Remove-Item $tmpTar -Force
-                    Log "Homebrew sha256: $sha"
-                } catch {
-                    Warn "Could not download tar.gz - set sha256 manually in the formula"
-                }
-            }
-
-            Set-Content -Path $formulaPath -Value $formula
-            Log "Homebrew formula updated: $formulaName"
-            if ($isPrerelease) {
-                Log "Users install beta with: brew install USER/tap/its-magic-beta"
-            } else {
-                Log "Users install stable with: brew install USER/tap/its-magic"
-            }
-        } else {
-            $formulaName = Split-Path -Leaf $formulaPath
-            Log "(dry-run) would update $formulaName"
-        }
-    } else {
-        Warn "Formula not found at $formulaPath - skipping Homebrew"
-    }
-
-    # Optional: publish formulas to Homebrew tap repository
-    if (-not $SkipBrewPush) {
-        if ($DryRun) {
-            Log "(dry-run) would publish formulas to Homebrew tap"
-        } else {
-            $gitAvailable = $null -ne (Get-Command git -ErrorAction SilentlyContinue)
-            $ghAvailableForTap = $null -ne (Get-Command gh -ErrorAction SilentlyContinue)
-            if (-not $gitAvailable) {
-                $brewTapFailed = $true
-                Warn "git not found - cannot push Homebrew formulas to tap"
-            } else {
-                if (-not $BrewTapRepo) {
-                    $originUrl = git remote get-url origin 2>$null
-                    if ($originUrl -match 'github\.com[:/](.+?)/(.+?)(\.git)?$') {
-                        $owner = $Matches[1]
-                        $BrewTapRepo = "$owner/homebrew-tap"
-                    }
-                }
-
-                if (-not $BrewTapRepo) {
-                    $brewTapFailed = $true
-                    Warn "Could not infer Homebrew tap repo. Pass -BrewTapRepo owner/homebrew-tap"
-                } else {
-                    if (-not $BrewTapDir) {
-                        $safeTap = ($BrewTapRepo -replace '[^a-zA-Z0-9_-]', '-')
-                        $BrewTapDir = Join-Path $env:TEMP "its-magic-$safeTap"
-                    }
-
-                    Log "Publishing formulas to tap $BrewTapRepo (branch: $BrewTapBranch) ..."
-
-                    # Use a child scope with relaxed error handling for git commands
-                    # that write to stderr even on success (e.g. empty repo warnings).
-                    $tapReady = $true
-                    $prevEAP = $ErrorActionPreference
-                    $ErrorActionPreference = 'Continue'
-
-                    # ── Step A: Ensure we have a local clone ──
-                    $tapGitDir = Join-Path $BrewTapDir ".git"
-
-                    # Clean up non-git directory leftovers
-                    if ((Test-Path $BrewTapDir) -and -not (Test-Path $tapGitDir)) {
-                        Warn "Tap directory exists but is not a git repo. Removing: $BrewTapDir"
-                        Remove-Item -Recurse -Force $BrewTapDir
-                    }
-
-                    if (Test-Path $tapGitDir) {
-                        # Already cloned - fetch latest
-                        git -C $BrewTapDir fetch origin 2>&1 | Out-Null
-                    } else {
-                        # Clone (try gh first, then git)
-                        $cloneOk = $false
-                        if ($ghAvailableForTap) {
-                            & gh repo clone $BrewTapRepo $BrewTapDir 2>&1 | Out-Null
-                            if ($LASTEXITCODE -eq 0) { $cloneOk = $true }
-                        }
-                        if (-not $cloneOk) {
-                            git clone "https://github.com/$BrewTapRepo.git" $BrewTapDir 2>&1 | Out-Null
-                            if ($LASTEXITCODE -eq 0) { $cloneOk = $true }
-                        }
-                        if (-not $cloneOk -and $CreateBrewTapIfMissing -and $ghAvailableForTap) {
-                            Warn "Tap repo not found. Creating $BrewTapRepo on GitHub ..."
-                            & gh repo create $BrewTapRepo --public --description "Homebrew tap for its-magic" 2>&1 | Out-Null
-                            if ($LASTEXITCODE -eq 0) {
-                                Log "Tap repo created: https://github.com/$BrewTapRepo"
-                                if (Test-Path $BrewTapDir) { Remove-Item -Recurse -Force $BrewTapDir }
-                                & gh repo clone $BrewTapRepo $BrewTapDir 2>&1 | Out-Null
-                                if ($LASTEXITCODE -eq 0) { $cloneOk = $true }
-                            }
-                        }
-                        if (-not $cloneOk) {
-                            $tapReady = $false; $brewTapFailed = $true
-                            Warn "Failed to clone/create tap repo $BrewTapRepo"
-                        }
-                    }
-
-                    # ── Step B: Ensure branch exists ──
-                    if ($tapReady) {
-                        # Check if repo has any commits at all
-                        $hasCommits = $false
-                        git -C $BrewTapDir log --oneline -1 2>&1 | Out-Null
-                        if ($LASTEXITCODE -eq 0) { $hasCommits = $true }
-
-                        if ($hasCommits) {
-                            git -C $BrewTapDir checkout $BrewTapBranch 2>&1 | Out-Null
-                            if ($LASTEXITCODE -ne 0) {
-                                git -C $BrewTapDir checkout -b $BrewTapBranch 2>&1 | Out-Null
-                            }
-                            # Try to pull if remote branch exists
-                            git -C $BrewTapDir pull origin $BrewTapBranch 2>&1 | Out-Null
-                        } else {
-                            Log "Empty tap repo detected - creating initial branch $BrewTapBranch"
-                            git -C $BrewTapDir checkout --orphan $BrewTapBranch 2>&1 | Out-Null
-                        }
-                    }
-
-                    # ── Step C: Copy formulas, commit, push ──
-                    if ($tapReady) {
-                        $tapFormulaDir = Join-Path $BrewTapDir "Formula"
-                        if (-not (Test-Path $tapFormulaDir)) {
-                            New-Item -ItemType Directory -Path $tapFormulaDir -Force | Out-Null
-                        }
-
-                        Copy-Item (Join-Path $repoRoot "packaging\homebrew\its-magic.rb") (Join-Path $tapFormulaDir "its-magic.rb") -Force
-                        Copy-Item (Join-Path $repoRoot "packaging\homebrew\its-magic-beta.rb") (Join-Path $tapFormulaDir "its-magic-beta.rb") -Force
-
-                        git -C $BrewTapDir add Formula/its-magic.rb Formula/its-magic-beta.rb
-
-                        $tapChanges = git -C $BrewTapDir status --porcelain
-                        if ($tapChanges) {
-                            git -C $BrewTapDir commit -m "chore: update its-magic formulas for $newVersion" 2>&1 | Out-Null
-                            if ($LASTEXITCODE -ne 0) {
-                                $brewTapFailed = $true
-                                Warn "Failed to commit Homebrew tap changes"
-                            } else {
-                                git -C $BrewTapDir push -u origin $BrewTapBranch 2>&1 | Out-Null
-                                if ($LASTEXITCODE -ne 0) {
-                                    $brewTapFailed = $true
-                                    Warn "Failed to push Homebrew tap changes"
-                                } else {
-                                    $brewTapPushed = $true
-                                    Log "Homebrew tap updated: https://github.com/$BrewTapRepo"
-                                }
-                            }
-                        } else {
-                            Log "No Homebrew formula changes to push"
-                        }
-                    }
-
-                    $ErrorActionPreference = $prevEAP
-                }
-            }
-        }
-    } else {
-        Warn "Skipping Homebrew tap push"
-    }
-} else {
-    Warn "Skipping Homebrew"
-}
-
-# ── Done ─────────────────────────────────────────────────────────────
-Pop-Location
-$npmStatus = "OK"
-if ($SkipNpm) { $npmStatus = "SKIPPED" }
-$chocoStatus = "OK"
-if ($SkipChoco) { $chocoStatus = "SKIPPED" }
-elseif ($DryRun) { $chocoStatus = "DRY-RUN" }
-elseif ($chocoFailed) { $chocoStatus = "FAILED - check log" }
-$brewStatus = "OK - formula updated"
-if ($SkipBrew) { $brewStatus = "SKIPPED" }
-elseif ($brewTapFailed) { $brewStatus = "FORMULA OK - TAP PUSH FAILED" }
-elseif ($brewTapPushed) { $brewStatus = "OK - formula updated + tap pushed" }
-
-Log "=========================================="
-Log "Release $newVersion complete!"
-Log "  npm:         $npmStatus"
-Log "  Chocolatey:  $chocoStatus"
-Log "  Homebrew:    $brewStatus"
-Log "=========================================="

package/sprints/S0001/progress.md

@@ -1,4 +0,0 @@
-# Progress
-
-- ...
-

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
-