feat: Phases 4-7 — Full Feature Expansion (26 features)

Phase 4 — New Widget Types: - Clock/Weather, System Stats, RSS/Feed, Calendar, Markdown, Metric/Counter, Link Group, Camera/Stream widgets - Backend services with caching for each data source - Full creation form with dynamic config fields per type Phase 5 — Visual & Styling Enhancements: - Glassmorphism card style (solid/glass/outline) - Board-level themes with per-board hue/saturation - Animated SVG status rings replacing static dots - Card size options (compact/medium/large) - Custom CSS injection (admin + per-board, sanitized) - Wallpaper backgrounds with blur/overlay/parallax Phase 6 — Functional Features: - Favorites bar with drag-and-drop reordering - Recent apps tracking with privacy toggle - Uptime dashboard page (/status, guest-accessible) - Notifications system (Discord/Slack/Telegram/HTTP webhooks) - App tags with filtering in board view - Multi-URL app cards with expandable sub-links - Personal API tokens with scoped permissions - Audit log with retention and admin viewer Phase 7 — Quality of Life: - Onboarding wizard (5-step first-launch setup) - App URL health preview with favicon/title detection - Board templates (4 built-in + custom import/export) - Keyboard shortcut overlay (j/k nav, 1-9 boards, ? help) 212 files changed, 15641 insertions, 980 deletions. Build, lint, type check, and 222 tests all pass.
2026-03-25 14:18:10 +03:00
parent 8d7847889e
commit 1c0a7cb850
212 changed files with 15642 additions and 981 deletions
@@ -9,15 +9,18 @@
 **Execution:** Orchestrator

 ## Summary
+
 Build a self-hosted web application launcher/dashboard for a TrueNAS server environment. The MVP includes local auth + guest mode, app CRUD with healthchecks, a single default board with sections and app widgets, an admin panel, dark theme with ambient backgrounds, and Docker deployment with Gitea CI.

 ## Build & Test Commands
+
 - **Build:** `npm run build`
 - **Test:** `npm test`
 - **Lint:** `npm run lint`
 - **Type Check:** `npm run check`

 ## Tech Stack
+
 - **Framework:** SvelteKit (Svelte 5 runes mode) + TypeScript strict
 - **UI:** Tailwind CSS v4 + shadcn-svelte (Bits UI) + Lucide Svelte + Simple Icons
 - **Data:** Prisma ORM + SQLite + Superforms + Zod
@@ -38,18 +41,19 @@ Build a self-hosted web application launcher/dashboard for a TrueNAS server envi

 ## Phase Progress Log

-| Phase | Domain | Status | Review | Build | Committed |
-|-------|--------|--------|--------|-------|-----------|
-| Phase 1: Scaffolding | backend | ✅ Complete | ✅ | ⬜ | ⬜ |
-| Phase 2: Database & Services | backend | ✅ Complete | ⬜ | ⬜ | ⬜ |
-| Phase 3: Authentication | fullstack | ✅ Complete | ⬜ | ⬜ | ⬜ |
-| Phase 4: App & Healthcheck | fullstack | ✅ Complete | ⬜ | ⬜ | ⬜ |
-| Phase 5: Board & Widgets | fullstack | ✅ Complete | ⬜ | ⬜ | ⬜ |
-| Phase 6: Admin Panel | fullstack | ✅ Complete | ⬜ | ⬜ | ⬜ |
-| Phase 7: UI Polish | frontend | ✅ Complete | ⬜ | ⬜ | ⬜ |
-| Phase 8: Integration & Deploy | fullstack | ✅ Complete | ✅ | ✅ | ⬜ |
+| Phase                         | Domain    | Status      | Review | Build | Committed |
+| ----------------------------- | --------- | ----------- | ------ | ----- | --------- |
+| Phase 1: Scaffolding          | backend   | ✅ Complete | ✅     | ⬜    | ⬜        |
+| Phase 2: Database & Services  | backend   | ✅ Complete | ⬜     | ⬜    | ⬜        |
+| Phase 3: Authentication       | fullstack | ✅ Complete | ⬜     | ⬜    | ⬜        |
+| Phase 4: App & Healthcheck    | fullstack | ✅ Complete | ⬜     | ⬜    | ⬜        |
+| Phase 5: Board & Widgets      | fullstack | ✅ Complete | ⬜     | ⬜    | ⬜        |
+| Phase 6: Admin Panel          | fullstack | ✅ Complete | ⬜     | ⬜    | ⬜        |
+| Phase 7: UI Polish            | frontend  | ✅ Complete | ⬜     | ⬜    | ⬜        |
+| Phase 8: Integration & Deploy | fullstack | ✅ Complete | ✅     | ✅    | ⬜        |

 ## Final Review
+
 - [ ] Comprehensive code review
 - [ ] Full build passes
 - [ ] Full test suite passes
@@ -5,6 +5,7 @@
 **Domain:** backend

 ## Objective
+
 Initialize the SvelteKit project with the full toolchain: TypeScript strict, Svelte 5, Tailwind CSS v4, shadcn-svelte, Prisma + SQLite, Vitest, ESLint, Prettier. Create the Docker and CI configuration.

 ## Tasks
@@ -24,6 +25,7 @@ Initialize the SvelteKit project with the full toolchain: TypeScript strict, Sve
 - [x] Task 13: Create `app.d.ts` with SvelteKit type augmentation (Locals, Session)

 ## Files to Modify/Create
+
 - `package.json` — project config with all dependencies and scripts
 - `svelte.config.js` — SvelteKit config with adapter-node
 - `vite.config.ts` — Vite config with Vitest
@@ -41,18 +43,21 @@ Initialize the SvelteKit project with the full toolchain: TypeScript strict, Sve
 - `.prettierrc` — Prettier config

 ## Acceptance Criteria
+
 - `npm install` succeeds
 - Project structure matches SvelteKit conventions
 - All config files are valid
 - Dockerfile builds (structure-wise, not the app itself yet)

 ## Notes
+
 - Use `@sveltejs/adapter-node` for Docker deployment
 - Svelte 5 runes mode is the default in latest SvelteKit — no special config needed
 - Tailwind v4 uses the new CSS-based config approach
 - ⚠️ Big Bang: build will not pass yet — no routes or components exist

 ## Review Checklist
+
 - [ ] All tasks completed
 - [ ] Code follows project conventions
 - [ ] No unintended side effects
@@ -5,6 +5,7 @@
 **Domain:** backend

 ## Objective
+
 Define the full Prisma database schema, run migrations, and build the core server-side services layer with shared Zod validation schemas and TypeScript type definitions.

 ## Tasks
@@ -24,6 +25,7 @@ Define the full Prisma database schema, run migrations, and build the core serve
 - [x] Task 13: Create `prisma/seed.ts` — seed admin user, default groups, default board, sample apps

 ## Files to Modify/Create
+
 - `prisma/schema.prisma` — full schema definition
 - `prisma/seed.ts` — seed script
 - `src/lib/types/*.ts` — type definitions
@@ -38,6 +40,7 @@ Define the full Prisma database schema, run migrations, and build the core serve
 - `src/lib/server/services/permissionService.ts`

 ## Acceptance Criteria
+
 - Prisma schema validates and migration runs
 - All services export clean async functions with proper types
 - Zod schemas match Prisma models
@@ -45,6 +48,7 @@ Define the full Prisma database schema, run migrations, and build the core serve
 - No circular dependencies between services

 ## Notes
+
 - SystemSettings is a singleton row — use upsert pattern
 - Permission resolution: User-level > Group-level > Default
 - Widget config is JSON — stored as String in SQLite, parsed at application layer
@@ -53,6 +57,7 @@ Define the full Prisma database schema, run migrations, and build the core serve
 - ⚠️ Big Bang: services won't be wired to routes yet

 ## Review Checklist
+
 - [x] All tasks completed
 - [x] Code follows project conventions
 - [x] No unintended side effects
@@ -62,6 +67,7 @@ Define the full Prisma database schema, run migrations, and build the core serve
 ## Handoff to Next Phase

 **What's ready for Phase 3:**
+
 - Prisma schema is defined and migrated. SQLite DB created at `data/launcher.db`.
 - Prisma client is generated and available via `src/lib/server/prisma.ts` singleton.
 - `authService.ts` provides: `hashPassword`, `verifyPassword`, `signAccessToken`, `verifyAccessToken`, `generateRefreshToken`, `saveRefreshToken`, `validateRefreshToken`, `revokeRefreshToken`, `rotateTokens`.
@@ -5,6 +5,7 @@
 **Domain:** fullstack

 ## Objective
+
 Implement the full local authentication flow: login, registration, session management with JWT + refresh tokens in HTTP-only cookies, auth middleware in hooks.server.ts, and guest mode support.

 ## Tasks
@@ -26,6 +27,7 @@ Implement the full local authentication flow: login, registration, session manag
 - [x] Task 15: Create logout endpoint/action — invalidate refresh token, clear cookies

 ## Files to Modify/Create
+
 - `src/hooks.server.ts` — auth middleware
 - `src/lib/server/utils/jwt.ts` — JWT utilities
 - `src/lib/server/utils/password.ts` — password utilities
@@ -43,6 +45,7 @@ Implement the full local authentication flow: login, registration, session manag
 - `src/app.d.ts` — augment `Locals` with user session type (already done in Phase 2)

 ## Acceptance Criteria
+
 - Users can register (when enabled) and log in with email/password
 - JWT access token + refresh token issued in HTTP-only cookies
 - `hooks.server.ts` validates tokens on every request and injects user into `event.locals`
@@ -53,6 +56,7 @@ Implement the full local authentication flow: login, registration, session manag
 - Form validation with Superforms + Zod shows errors inline

 ## Notes
+
 - Access token expiry: 15 minutes; Refresh token expiry: 7 days
 - Store refresh tokens in DB (User model) for server-side invalidation
 - OAuth is deferred to Phase 2 of the project (post-MVP)
@@ -60,6 +64,7 @@ Implement the full local authentication flow: login, registration, session manag
 - Big Bang: login page will be functional but unstyled/minimal until Phase 7

 ## Review Checklist
+
 - [x] All tasks completed
 - [x] Code follows project conventions
 - [x] No unintended side effects
@@ -69,6 +74,7 @@ Implement the full local authentication flow: login, registration, session manag
 ## Handoff to Next Phase

 **What's ready for Phase 4:**
+
 - Full local auth flow is implemented: login, registration, logout, token refresh.
 - `hooks.server.ts` validates JWT access tokens on every request and injects `event.locals.user` and `event.locals.session`. Expired access tokens are silently refreshed via refresh token rotation.
 - Protected routes (anything except `/login`, `/register`, `/auth/*`, `/api/health`) redirect unauthenticated users to `/login`.
@@ -5,6 +5,7 @@
 **Domain:** fullstack

 ## Objective
+
 Build the app (service) registry with CRUD operations, the icon resolution system, healthcheck scheduler with node-cron, and status APIs. Create the app management UI.

 ## Tasks
@@ -25,6 +26,7 @@ Build the app (service) registry with CRUD operations, the icon resolution syste
 - [x] Task 14: Handle custom icon uploads — file upload endpoint + static serving from `static/uploads/`

 ## Files to Modify/Create
+
 - `src/routes/api/apps/+server.ts`
 - `src/routes/api/apps/[id]/+server.ts`
 - `src/routes/api/apps/[id]/status/+server.ts`
@@ -40,6 +42,7 @@ Build the app (service) registry with CRUD operations, the icon resolution syste
 - `src/lib/components/app/AppHealthBadge.svelte`

 ## Acceptance Criteria
+
 - Apps can be created, read, updated, deleted via API
 - Healthcheck scheduler runs on configured intervals per app
 - Status is correctly derived: online/offline/degraded/unknown
@@ -48,6 +51,7 @@ Build the app (service) registry with CRUD operations, the icon resolution syste
 - Docker health endpoint returns 200 when server is running

 ## Notes
+
 - Healthcheck runs in-process via node-cron (no external job runner)
 - Default healthcheck: HTTP HEAD to app URL, expect 200, 5s timeout, 60s interval
 - Store last N status records in AppStatus for history (sparklines are post-MVP)
@@ -55,6 +59,7 @@ Build the app (service) registry with CRUD operations, the icon resolution syste
 - ⚠️ Big Bang: pages will be functional but minimally styled until Phase 7

 ## Review Checklist
+
 - [x] All tasks completed
 - [x] Code follows project conventions
 - [x] No unintended side effects
@@ -5,6 +5,7 @@
 **Domain:** fullstack

 ## Objective
+
 Build the board/section/widget system — the core UI of the dashboard. Implement CRUD APIs, the board view page with collapsible sections and app widgets in a responsive grid, and the board editor.

 ## Tasks
@@ -31,6 +32,7 @@ Build the board/section/widget system — the core UI of the dashboard. Implemen
 - [x] Task 20: Create `src/lib/components/widget/WidgetGrid.svelte` — responsive grid layout for widgets

 ## Files to Modify/Create
+
 - `src/routes/api/boards/+server.ts`
 - `src/routes/api/boards/[id]/+server.ts`
 - `src/routes/api/boards/[id]/sections/+server.ts`
@@ -47,6 +49,7 @@ Build the board/section/widget system — the core UI of the dashboard. Implemen
 - `src/lib/components/widget/*.svelte`

 ## Acceptance Criteria
+
 - Boards can be created, listed, viewed, edited, deleted
 - Sections within boards support CRUD and ordering
 - Widgets within sections support CRUD and ordering
@@ -56,6 +59,7 @@ Build the board/section/widget system — the core UI of the dashboard. Implemen
 - Default board is accessible from root page

 ## Notes
+
 - MVP supports only AppWidget type; schema should have `type` field for future widget types
 - Widget config is JSON: `{ appId: string }` for AppWidget
 - Section collapse uses Svelte `slide` transition
@@ -64,6 +68,7 @@ Build the board/section/widget system — the core UI of the dashboard. Implemen
 - Big Bang: functional but minimally styled until Phase 7

 ## Review Checklist
+
 - [x] All tasks completed
 - [x] Code follows project conventions
 - [x] No unintended side effects
@@ -73,6 +78,7 @@ Build the board/section/widget system — the core UI of the dashboard. Implemen
 ## Handoff to Next Phase

 Phase 5 is complete. All board, section, and widget CRUD APIs are implemented with permission-based filtering (admin sees all, regular users see permitted boards, guests see guest-accessible boards only). The board view page loads the full board hierarchy (board -> sections -> widgets -> app + status) via `boardService.findBoardById`. The board editor provides form-based management of board properties, sections (add/delete), and widgets (add app widgets from a dropdown, remove). All Svelte components use runes mode and follow existing patterns:
+
 - `Board.svelte` renders sections in order
 - `Section.svelte` uses `SectionHeader` (chevron toggle) + `SectionCollapsible` (Svelte `slide` transition)
 - `WidgetGrid.svelte` uses a responsive CSS grid (2/3/4 cols)
@@ -80,6 +86,7 @@ Phase 5 is complete. All board, section, and widget CRUD APIs are implemented wi
 - `BoardCard.svelte` shows board summary with section count, default/guest badges

 Key files for Phase 6 (Admin Panel):
+
 - Board API routes at `/api/boards/**` are ready for admin operations
 - Permission checking via `permissionService.checkPermission()` is integrated into all write operations
 - Board editor at `/boards/[boardId]/edit` is functional for admin use
@@ -5,6 +5,7 @@
 **Domain:** fullstack

 ## Objective
+
 Build the admin panel with user management, group management, app management, board management, and system settings configuration.

 ## Tasks
@@ -29,6 +30,7 @@ Build the admin panel with user management, group management, app management, bo
 - [x] Task 18: Create `src/routes/api/search/+server.ts` — global search endpoint (searches apps + boards)

 ## Files to Modify/Create
+
 - `src/routes/admin/+layout.server.ts`
 - `src/routes/admin/+layout.svelte`
 - `src/routes/admin/users/+page.server.ts`
@@ -46,6 +48,7 @@ Build the admin panel with user management, group management, app management, bo
 - `src/lib/components/admin/*.svelte`

 ## Acceptance Criteria
+
 - Admin-only routes are protected (non-admin users get 403/redirect)
 - Users can be created, edited, deleted, assigned to groups
 - Groups can be created, edited, deleted
@@ -54,6 +57,7 @@ Build the admin panel with user management, group management, app management, bo
 - All forms use Superforms + Zod validation

 ## Notes
+
 - Admin role is checked in `+layout.server.ts` — redirect non-admins
 - User creation by admin sets password directly (no email verification in MVP)
 - OAuth config fields in settings are stored but non-functional until post-MVP Phase 2
@@ -61,6 +65,7 @@ Build the admin panel with user management, group management, app management, bo
 - ⚠️ Big Bang: functional but minimally styled until Phase 7

 ## Review Checklist
+
 - [x] All tasks completed
 - [x] Code follows project conventions
 - [x] No unintended side effects
@@ -70,6 +75,7 @@ Build the admin panel with user management, group management, app management, bo
 ## Handoff to Next Phase

 **What was built:**
+
 - Admin layout with auth guard (`requireAdmin`) and navigation (Users/Groups/Settings + Back to Dashboard)
 - User management: full CRUD via Superforms, inline role editing, group membership management (add/remove), delete with confirmation
 - Group management: full CRUD via Superforms, inline editing, member count display, default group toggle
@@ -81,6 +87,7 @@ Build the admin panel with user management, group management, app management, bo
 - Self-deletion protection: admin cannot delete their own account

 **Available for Phase 7:**
+
 - All admin components in `src/lib/components/admin/` (UserTable, GroupTable, SettingsForm, PermissionEditor) — ready for UI polish
 - Admin layout nav bar — can be styled with active states, icons
 - PermissionEditor is a reusable client-side component with callback props (`onGrant`/`onRevoke`) — can be integrated into any admin page
@@ -5,6 +5,7 @@
 **Domain:** frontend

 ## Objective
+
 Polish the entire UI: implement the root layout with sidebar and header, dark/light/system theme with HSL customization, ambient animated backgrounds, page transitions, animations, skeleton loading states, and responsive design.

 ## Tasks
@@ -35,6 +36,7 @@ Polish the entire UI: implement the root layout with sidebar and header, dark/li
 - [x] Task 24: Polish all existing pages (apps, boards, admin) with consistent component styling

 ## Files to Modify/Create
+
 - `src/lib/components/layout/MainLayout.svelte`
 - `src/lib/components/layout/Sidebar.svelte`
 - `src/lib/components/layout/Header.svelte`
@@ -54,6 +56,7 @@ Polish the entire UI: implement the root layout with sidebar and header, dark/li
 - Various existing component files — add animations, polish styling

 ## Acceptance Criteria
+
 - Dark/Light/System theme works with smooth CSS transitions
 - HSL-based primary color customization works
 - At least one ambient background (mesh gradient) animates smoothly
@@ -68,6 +71,7 @@ Polish the entire UI: implement the root layout with sidebar and header, dark/li
 - Layout is responsive at desktop (>1024px), tablet (768-1024px), mobile (<768px)

 ## Notes
+
 - Use Svelte 5 runes for stores, NOT legacy `writable`/`readable`
 - Use `svelte/motion` (tweened, spring) for ambient animations
 - AmbientBackground should be configurable and toggleable
@@ -76,6 +80,7 @@ Polish the entire UI: implement the root layout with sidebar and header, dark/li
 - Use Tailwind utility classes as primary styling approach

 ## Review Checklist
+
 - [x] All tasks completed
 - [x] Code follows project conventions
 - [x] No unintended side effects
@@ -5,6 +5,7 @@
 **Domain:** fullstack

 ## Objective
+
 Integrate all phases into a fully working application. Fix all build errors, add test coverage, verify Docker deployment, and finalize the CI pipeline. This is the Big Bang convergence phase — everything must work after this.

 ## Tasks
@@ -29,6 +30,7 @@ Integrate all phases into a fully working application. Fix all build errors, add
 ## Files Modified/Created

 ### Build fixes
+
 - `src/lib/components/admin/SettingsForm.svelte` — Fixed JSON curly brace escaping in placeholder
 - `src/lib/server/services/authService.ts` — Fixed JWT `expiresIn` type cast for zod 3.25+
 - `src/lib/stores/theme.svelte.ts` — Reordered `#systemPreference` initialization before `$derived`
@@ -42,6 +44,7 @@ Integrate all phases into a fully working application. Fix all build errors, add
 - `src/lib/components/app/AppForm.svelte` — Fixed iconType type cast

 ### Lint fixes
+
 - `eslint.config.js` — Disabled `svelte/no-navigation-without-resolve` for static routes
 - `src/lib/components/admin/PermissionEditor.svelte` — Added `{#each}` keys
 - `src/lib/components/admin/UserTable.svelte` — Added `{#each}` key
@@ -52,6 +55,7 @@ Integrate all phases into a fully working application. Fix all build errors, add
 - `src/routes/boards/[boardId]/edit/+page.server.ts` — Removed unused `redirect` import

 ### Tests (NEW)
+
 - `src/lib/utils/__tests__/cn.test.ts` — cn() utility tests
 - `src/lib/utils/__tests__/constants.test.ts` — Constants coverage tests
 - `src/lib/utils/__tests__/validators.test.ts` — Zod schema validation tests (35 tests)
@@ -64,6 +68,7 @@ Integrate all phases into a fully working application. Fix all build errors, add
 - `src/lib/server/services/__tests__/permissionService.test.ts` — Permission service tests

 ### Docker & config
+
 - `Dockerfile` — Added prisma migrate deploy on container startup
 - `vite.config.ts` — Changed test environment from jsdom to node
 - `prisma/seed.ts` — Expanded with regular user, 7 apps, 3 sections, idempotent seeding
@@ -82,6 +87,7 @@ Integrate all phases into a fully working application. Fix all build errors, add
 The main convergence issue was **zod 3.25 incompatibility** with sveltekit-superforms v2's `ZodObjectType` constraint. Fixed with a typed wrapper in `src/lib/utils/zod-adapter.ts` that preserves type inference while bypassing the constraint boundary.

 ## Review Checklist
+
 - [x] All critical tasks completed
 - [x] Code follows project conventions
 - [x] No unintended side effects
@@ -89,7 +95,9 @@ The main convergence issue was **zod 3.25 incompatibility** with sveltekit-super
 - [x] Tests pass (new + existing)

 ## Handoff
+
 Phase 8 core tasks complete. Remaining items for future iteration:
+
 - API integration tests and component tests (Tasks 7-8)
 - Full coverage analysis (Task 9)
 - Docker runtime verification (Tasks 12-13)