From bc4f90f3fa91f0eb3d7a0bb0007612f44bed454c Mon Sep 17 00:00:00 2001 From: xpltd Date: Tue, 17 Mar 2026 21:27:21 -0500 Subject: [PATCH] docs: start milestone v1.0 Initial Release --- .planning/PROJECT.md | 31 +++++++++++++++++++++++++++---- .planning/STATE.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+), 4 deletions(-) create mode 100644 .planning/STATE.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index 514a665..53b1972 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -10,6 +10,19 @@ Not a MeTube fork. A ground-up rebuild that treats theming, session behavior, pu A user can paste any yt-dlp-supported URL, see exactly what they're about to download, and get it — without creating an account, without sending data anywhere, and without knowing what a terminal is. +## Current Milestone: v1.0 Initial Release + +**Goal:** Ship a fully functional, self-hostable yt-dlp web frontend — downloads, session management, theming, admin auth, and Docker distribution. + +**Target features:** +- Core download engine (URL detection, format selection, real-time progress) +- Session system (cookie-based, isolated by default, export/import) +- Theming (cyberpunk default, dark, light; drop-in custom themes) +- Admin UI with basic login (Sonarr-style) and live config management +- Health, observability, privacy controls +- Docker distribution with CI/CD pipeline +- Post-ship polish phase (defaults tuning) + ## Requirements ### Validated @@ -32,6 +45,8 @@ A user can paste any yt-dlp-supported URL, see exactly what they're about to dow - [ ] Session cookie (`mrip_session`) auto-created on first visit, 24hr TTL - [ ] Session persists across browser refresh and reconnects (SSE replays state on reconnect) - [ ] User can delete their own session and all associated data (downloads, logs, cookies) +- [ ] User can export their session as a portable file (download history, queue state, preferences) +- [ ] User can import a previously exported session to restore their download history — enables basic identity continuity on persistent instances - [ ] Cookie auth: user can upload a `cookies.txt` file (Netscape format) per-session for authenticated downloads (private/paywalled content) **Link Sharing** @@ -42,15 +57,19 @@ A user can paste any yt-dlp-supported URL, see exactly what they're about to dow - [ ] Three built-in themes: cyberpunk (default), dark, light - [ ] Theme selection persisted in localStorage - [ ] Operators can drop theme directories into `/themes` volume — appears in picker without recompile +- [ ] Theme file format is flat, well-commented, and human-readable — a single file per theme with clear variable names and inline docs so anyone (or an AI) can understand and modify it without prior CSS/frontend knowledge +- [ ] Built-in themes serve as learning examples: heavily commented, covering every UI region, showing what each token controls - [ ] Responsive layout: desktop (sidebar + table) and mobile (bottom tabs + card list) - [ ] All touch targets minimum 44px on mobile **Admin & Configuration** +- [ ] Admin login: username/password protected admin UI (like qBittorrent/Sonarr/Radarr) — no token-in-header, no raw config required; default credentials set at first boot with forced change prompt +- [ ] Admin panel is the primary config surface — session mode, purge policy, filename templates, branding all configurable via UI without touching files +- [ ] `config.yaml` mount still supported as override layer for operators who prefer infra-as-code / GitOps workflows - [ ] Operator can configure session mode: `isolated` (default) / `shared` / `open` - [ ] Operator can configure purge: `scheduled` / `manual` / `never`, with TTL for files and logs independently - [ ] Operator can configure output filename templates globally (source-aware: YouTube, SoundCloud, generic) -- [ ] Operator can set `ADMIN_TOKEN` to protect admin routes -- [ ] Admin panel: active sessions, storage usage, manual purge trigger, unsupported URL log download, sanitized config view +- [ ] Admin panel: active sessions, storage usage, manual purge trigger, unsupported URL log download, live config editor - [ ] Branding overridable: name, tagline, logo **Health & Observability** @@ -79,7 +98,7 @@ A user can paste any yt-dlp-supported URL, see exactly what they're about to dow ### Out of Scope - External API / arr-stack integration (Radarr/Sonarr-style programmatic use) — documented as future milestone, architecture should not block it -- OAuth / user accounts — no identity system; sessions are anonymous by design +- OAuth / user accounts — end-user sessions are anonymous by design; admin auth is basic username/password only, no SSO - Real-time chat or social features — not core - Video posts or re-hosting — media.rip downloads, does not transcode or re-serve content at scale - Mobile native app — web-first @@ -92,6 +111,7 @@ A user can paste any yt-dlp-supported URL, see exactly what they're about to dow - yt-dlp used as library (`import yt_dlp`), not subprocess — gives fine-grained progress hooks and avoids shell injection - Session cookie approach chosen so users can reconnect after internet drop and resume where they left off - Cookie auth (cookies.txt upload) enables downloading paywalled/private content without embedding credentials in the app +- A post-ship polish phase is planned: after the core product is working, do a dedicated pass to tune defaults, tighten the out-of-box experience, and make the cyberpunk theme sing ## Constraints @@ -110,6 +130,9 @@ A user can paste any yt-dlp-supported URL, see exactly what they're about to dow | Session isolation as default | Privacy-first default; operators opt into shared/open | — Pending | | cookies.txt upload (Netscape format) | yt-dlp native support, well-documented browser extension workflow for users | — Pending | | External API deferred to v2 | Keeps v1 scope manageable; current API surface designed cleanly so future consumers aren't blocked | — Pending | +| Admin UI auth (basic login) over ADMIN_TOKEN | Lowers barrier for non-technical operators; config-via-UI means no docker restarts to change settings; `config.yaml` still supported as override layer | — Pending | +| Session export/import | Enables identity continuity on persistent instances without a real account system; stays anonymous-first by default | — Pending | +| Theme files human-readable + heavily commented | Lowers floor for customization to near zero — anyone with a text editor or AI assistant can retheme without frontend knowledge | — Pending | --- -*Last updated: 2026-03-17 after initialization* +*Last updated: 2026-03-17 — added session export/import, theme file accessibility goals, admin basic auth login, polish phase* diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..23bde08 --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,43 @@ +# Project State + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-03-17) + +**Core value:** A user can paste any yt-dlp-supported URL, see exactly what they're about to download, and get it — without creating an account, without sending data anywhere, and without knowing what a terminal is. + +**Current focus:** Milestone v1.0 — defining requirements + +## Current Position + +Phase: Not started (defining requirements) +Plan: — +Status: Defining requirements +Last activity: 2026-03-17 — Milestone v1.0 started + +## Progress + +`[░░░░░░░░░░] 0%` + +## Recent Decisions + +| Decision | Outcome | +|----------|---------| +| Tech Stack | Python 3.12 + FastAPI, Vue 3 + TypeScript + Vite + Pinia, SQLite, SSE, APScheduler | +| Admin UI auth (basic login) over ADMIN_TOKEN | Pending | +| Session export/import | Pending | +| Theme files human-readable + heavily commented | Pending | + +## Pending Todos + +(none) + +## Blockers / Concerns + +(none) + +## Session Continuity + +Last session: 2026-03-17 +Stopped at: Milestone v1.0 started, proceeding to requirements definition +Resume file: none