From 55b90c6c1ab1cc452069ed7199684db9b9eb001f Mon Sep 17 00:00:00 2001 From: Kian Khayat <251517302+cianium@users.noreply.github.com> Date: Tue, 20 Oct 2026 16:02:12 +0330 Subject: [PATCH 1/4] docs: replace historical front page with preview-aware German Library README --- README.md | 150 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 104 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 697cdf9..c7c7333 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,121 @@ -# German Library v3.2.1-p0-preview — Security & SSR Navigation Patch +
-**این نسخه Source-only است، Production نیست.** پچ امنیتی جدید `backend/migrations/20261015_p0_article_source_read_access.sql` باید **پس از** Migration مقالات vNext روی Supabase Development اجرا و با حساب‌های واقعی آزمایش شود. بدون اجرای SQL، مشکل دسترسی به نسخه در حال ویرایش حل نشده است. مسیرهای SSR مقالات چهارمقصدی و هماهنگ با V7.5 شده‌اند؛ SEO URL خالی هم اصلاح شده است. گزارش کامل: `docs/P0_SECURITY_AND_NAV_REPORT_FA.md`. +# German Library -تست‌ها: `npm run qa`، `npm run qa:ssr:browser` و `npm run qa:studio:browser`. Build آزمایشی جای تست دیتابیس واقعی را نمی‌گیرد. +**A mobile-first German learning resource library for CEFR A1–C2.** ---- +[![Source QA and Build](https://github.com/cianium/German-Library/actions/workflows/ci.yml/badge.svg)](https://github.com/cianium/German-Library/actions/workflows/ci.yml) +![Status](https://img.shields.io/badge/Status-Development%20Preview-E5A50A) +![Version](https://img.shields.io/badge/Source-3.2.1--p0--preview-147D8B) -# German Library v3.2.0-preview — Article Studio Mobile Increment +**Books & learning resources · Articles · Content management · Multi-device experience** -**این بسته یک توسعه افزایشی است و جایگزین کامل نیازمندی‌های V7.5 نیست.** -- ناوبری عمومی چهارمقصدی V7.5 با Articles زیر Extras؛ پنل مدیریت تغییر نکرده است. -- جدول‌ساز، ویرایش لینک داخلی/خارجی، Alt و Caption جداگانه و ویرایش تصویر موجود. -- اصلاح باگ حفظ متادیتا هنگام باز کردن مقاله و بهبود SEO تصویر. -- دستور تست: `npm run qa`؛ تست UI با Chromium و Playwright: `npm run qa:studio:browser`. -- مستندات تغییرات و محدودیت‌ها: `docs/VNEXT_MOBILE_STUDIO_DELTA_FA.md`. -- آپلود امن تصاویر در Editor، Structured Editor Engine و Live Supabase/RLS QA **هنوز انجام نشده است**. -- برای ساخت Production باید `SUPABASE_URL`، `SUPABASE_PUBLISHABLE_KEY` و `SITE_URL` واقعی و امن را تنظیم کنی؛ `dist/` آزمایشی در فایل ZIP تحویلی قرار ندارد. +
---- +> **Release status:** This repository is currently a **source/preview build**, not a verified production release. The P0 article-access SQL patch exists in source, but its application to any real Supabase database and live role-based access verification are **not confirmed**. Do not use a passing CI run as evidence that deployed database permissions are secure. -# German Library v3 (Source release) +## What this project does -This v3 release is derived from German Library V7.4.0; it **is not** the older V7.3 release. +German Library helps German learners find curated learning materials by **CEFR level (A1–C2)**, book category, and learning objective. The codebase includes a browser-first catalog, content-management interfaces, an article authoring workflow, and Vercel server-rendered article endpoints. -## What's in v3.1 -- Five destinations: **سطح → مکمل → خانه → مقالات → کتابخانه**. -- Books-only library: categories and featured shelf; all published books regardless of level. -- Admin book editor: stable ID, book type, skills, optional CEFR, featured flag, cover URL/upload, book URL/upload, provider, status, core selection. -- Book assets: audio, podcast, video, transcript are still editable inside a book. -- Dedicated levels directory; independent media in Supplemental tab. -- Calm teal/blue-green light and deep-slate dark palette. -- Vercel server-rendered Articles directory and individual article pages, with raw SEO metadata, JSON-LD, sitemap, 404, and slug redirects. -- Supabase Article Studio workflow, private preview, revision history, optimistic concurrency, SEO checklist, and Admin-only Author assignment with audit. -- Additive Article and role migration: `backend/migrations/20261014_vnext_articles.sql`. +| Area | Included in source | Important boundary | +| :--- | :--- | :--- | +| Learning catalog | Levels, books, book-linked media, supplemental resources | The starter catalog is example content; access rights to third-party resources must be respected | +| Public interface | Mobile-first pages, navigation, responsive layouts | Check physical browsers before declaring release-ready | +| Administration | Content editing, status and sync-related workflows | Live Supabase Auth, Storage and permission checks still required | +| Article platform | SSR directory/article routes, SEO metadata, author/editor flows and preview | Live RLS migration and permission matrix must be verified on Staging | +| Quality checks | Static/source QA, mocked backend/SSR tests, build and dist inspection | Mocked tests do **not** validate a live database or deployed security | -## Run locally on Termux -Extract to a clean directory and run `python -m http.server 8080`; visit `http://127.0.0.1:8080/index.html`. **Never serve an old `dist` directory.** Offline mode uses sample content and a local Demo admin only on localhost. Live authentication/uploads need Supabase. +## Technology -## Article routes +- **Frontend:** HTML, CSS and JavaScript (mobile-first). +- **Server-rendered articles:** Vercel Functions and server-side navigation. +- **Backend services (when configured):** Supabase Auth, PostgreSQL/RLS and private Storage. +- **Build and QA:** Node.js (20+) and Python 3. +- **Deployment configuration:** `vercel.json`, with a separate static GitHub Pages deployment history. -Article HTML and `/sitemap.xml` run as Vercel Functions. `python -m http.server` does not execute these routes. Configure `SUPABASE_URL`, `SUPABASE_PUBLISHABLE_KEY`, and `SITE_URL` in Vercel. The publishable key is safe for browser use; no service-role key is required by the article renderer. +## Run locally (source preview) -## Supabase release order -1. Back up Production database and storage. -2. In Development, apply `backend/migrations/20261014_v74_books_media.sql` if missing, then `backend/migrations/20261014_v3_book_metadata.sql`. -3. Apply `backend/migrations/20261014_vnext_articles.sql` **then** `backend/migrations/20261015_p0_article_source_read_access.sql` in Development; run both `backend/validation/vnext_articles_check.sql` and `backend/validation/p0_article_access_check.sql` and live positive/negative role tests. -4. Set public Supabase URL, publishable key and `SITE_URL` in Vercel; never expose service-role keys. -5. Deploy Preview and verify existing Staff, book uploads and sync, plus article login, autosave, RLS, publishing, raw HTML, canonical, redirects and sitemap. -6. Only after successful Preview testing, plan a separate Production migration and deployment. No live Supabase migration or Production deployment was performed in this build. +Requirements: Node.js 20+ and Python 3. -## QA -`npm run qa` then `npm run build` then `npm run verify:dist`. The mocked Function and raw-HTML checks run in `tools/vnext-articles-qa.mjs`. Local browser QA: `python3 tools/v3-browser-qa.py` (requires Python Playwright and Chromium); it does not verify live Supabase. +```bash +git clone https://github.com/cianium/German-Library.git +cd German-Library +python3 -m http.server 8080 +``` -## Article platform boundaries +Open **http://localhost:8080** to view the static pages. This local static server does **not** execute Vercel article routes (`/articles`, `/articles/:slug`, `/sitemap.xml`), nor does it provision Supabase. Local demo behavior is **not** a production authentication or access-control test. -The editor currently uses browser `contenteditable` with allow-list serialization. Cover and inline images require stable public HTTPS URLs. Private draft bucket policies and asset metadata are prepared, but in-editor uploads, crop/focal-point tools, draft-to-public asset promotion, scheduled publishing, and live Supabase tests are not implemented. +## Quality checks -## Known constraints -- Level/category changes on existing books with dependent files are blocked to preserve referential integrity; move assets first. -- Cover upload uses existing private Supabase Storage; public viewing requires the current bucket signed-download rules. -- External links are structurally validated but not automatically health-checked. -- Migration is not automatically executed on any live database. +```bash +npm run qa +``` + +This runs the repository's static checks, content validation and **mocked** backend/article security regression checks. + +To assemble and inspect a **non-deployable CI test artifact** without using real Supabase credentials: + +```bash +SUPABASE_URL=https://ci-placeholder.supabase.co \ +SUPABASE_PUBLISHABLE_KEY=sb_publishable_ci_placeholder_not_a_real_key \ +SITE_URL=https://example.invalid \ +npm run build + +npm run verify:dist +``` + +These intentionally fake public values satisfy build-time configuration checks only. **Do not deploy that artifact.** A production deployment requires its own reviewed environment, approved public configuration, staged database migration, and live verification. + +Additional browser tests (require appropriate local tooling/Playwright + Chromium): + +```bash +npm run qa:ssr:browser +npm run qa:studio:browser +``` + +The GitHub Actions workflow runs **source QA + placeholder build + dist verification**. It does **not** run real Supabase migrations, live permission tests, or these separate browser suites. + +## Security & staging release gate + +Before enabling a real deployment, follow the documented migration order and verify RLS **in an authorized Development/Staging Supabase project**, including the P0 patch `backend/migrations/20261015_p0_article_source_read_access.sql`. Validate permissions for guest, learner, owning author, non-owning author, and editor/admin against both raw article rows and published snapshots. + +Do not apply a patch blindly to Production. Back up data, check migration history, and complete positive/negative access tests in Staging first. The patch being committed to GitHub is **not** proof it is deployed. + +- [P0 security and SSR navigation report (FA)](docs/P0_SECURITY_AND_NAV_REPORT_FA.md) +- [Supabase setup and staged verification](docs/SUPABASE_SETUP.md) +- [QA and historical technical audits](docs/TECHNICAL_AUDIT.md) +- [Release checklist (FA)](docs/RELEASE_CHECKLIST_FA.md) + +## Architecture and repository guide + +| Path | Responsibility | +| :--- | :--- | +| `assets/` | Shared UI, browser code, client-facing pages and styles | +| `data/` | Public fallback catalog content | +| `api/` | Vercel article and sitemap functions | +| `server/` | Shared server-side presentation helpers | +| `backend/migrations/` | Versioned database migrations **requiring explicit deployment** | +| `backend/validation/` | SQL validation scripts for staging checks | +| `tools/` | Source QA, mocked tests and optional browser checks | +| `docs/` | Product scope, security and delivery reports | + +## Roadmap + +- [ ] Verify live P0 permissions and draft/published-article boundaries in Staging. +- [ ] Complete responsive and accessibility testing in real mobile browsers. +- [ ] Validate Auth, Storage, and the article publish/review flow end-to-end. +- [ ] Improve the secure article media workflow. +- [ ] Publish a tested release with aligned versioning, migration instructions and rollback steps. + +## Versioning and historical releases + +The current `package.json` source version is **`3.2.1-p0-preview`**. GitHub also contains an older release **titled `v7.1.1` with tag `v1.1.1`**. Those identifiers refer to different versioning contexts; the old tag must not be silently moved or rewritten. + +Read the [Changelog](CHANGELOG.md) and [GitHub Releases and publishing policy](docs/RELEASES.md). A CI-green badge does **not** mean the project is production-ready. + +## Contributions and licensing + +Suggestions and reproducible bug reports are welcome through GitHub Issues. Please verify the status and current architecture before proposing changes. This public repository's contents are **not automatically licensed for reuse**; no open-source license is assumed until one is expressly added by the maintainer. For third-party learning materials, link to official publisher resources or use assets you are authorized to share. + +**Maintained by [Kian Khayat](https://github.com/cianium).** From 4a09b02035acb3a709aaef2a076c42771d344ddf Mon Sep 17 00:00:00 2001 From: Kian Khayat <251517302+cianium@users.noreply.github.com> Date: Tue, 20 Oct 2026 16:02:14 +0330 Subject: [PATCH 2/4] ci: verify German Library source and placeholder build --- .github/workflows/ci.yml | 59 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..48c5324 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,59 @@ +name: Source QA and Build + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: source-ci-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + verify: + name: Source QA and placeholder build + runs-on: ubuntu-latest + timeout-minutes: 15 + + # These intentionally fake values are for artifact-shape checks only. + # Never deploy the generated dist/ or connect this job to a real database. + env: + SUPABASE_URL: https://ci-placeholder.supabase.co + SUPABASE_PUBLISHABLE_KEY: sb_publishable_ci_placeholder_not_a_real_key + SITE_URL: https://example.invalid + + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '22' + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run source and mocked security QA + run: npm run qa + + - name: Build using non-production placeholders + run: npm run build + + - name: Verify output contains only expected public files + run: npm run verify:dist + + - name: Confirm CI placeholders were used + run: | + grep -F 'https://ci-placeholder.supabase.co' dist/assets/runtime-config.js + grep -F 'sb_publishable_ci_placeholder_not_a_real_key' dist/assets/runtime-config.js + if grep -R -l -E '(sb_secret_|service_role)' dist/assets/runtime-config.js; then + echo 'Unexpected privileged credential marker in generated config' + exit 1 + fi From 00bee9324fbe9961dd0cc3bea7e318ac8f127c72 Mon Sep 17 00:00:00 2001 From: Kian Khayat <251517302+cianium@users.noreply.github.com> Date: Tue, 20 Oct 2026 16:02:16 +0330 Subject: [PATCH 3/4] docs: clarify German Library historical release and release gates --- docs/RELEASES.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/RELEASES.md diff --git a/docs/RELEASES.md b/docs/RELEASES.md new file mode 100644 index 0000000..bd606c6 --- /dev/null +++ b/docs/RELEASES.md @@ -0,0 +1,38 @@ +# GitHub releases and publishing policy — German Library + +**Current source version:** `3.2.1-p0-preview` (as recorded in `package.json` on 2026-10-20). + +**Status:** Preview/source only. No documented execution of the current P0 security migration against an authorized live database, no independently verified Production rollout, and no live role-based security acceptance. + +## Historical GitHub Release + +As of 2026-10-20, the repository has one GitHub Release: + +| Git tag | Displayed Release title | Published (UTC) | Current interpretation | +| :--- | :--- | :--- | :--- | +| `v1.1.1` | `v7.1.1` | 2026-10-17 00:32 | Historical release; inconsistent tag/title, not the current preview | + +**Do not retag or delete the historical release.** The current GitHub integration does not expose metadata editing for Release objects. A maintainer should inspect the original commit and notes, then optionally rename the *display title* (not the tag) to: + +`German Library — Historical v7.1.1 snapshot (tag v1.1.1)` + +Suggested introductory disclaimer: + +> This is a historical source snapshot. Its Git tag is `v1.1.1` while the original displayed title was `v7.1.1`. Current repository source is `3.2.1-p0-preview`; no live Supabase migration or Production readiness is implied. See the current README and security report before deploying. + +Preserve the original body below the clarification and retain historical tags, dates and assets. + +## Release gate for future versions + +1. Record a **single version source of truth** in `package.json`; align release title, new tag and `CHANGELOG.md` when publishing a genuinely new release. +2. Confirm security migrations in **Development/Staging**, never from GitHub CI against Production. Keep appropriate backups and migration history. +3. Run live role-permission tests for unpublished and published snapshots. Verify Auth, private Storage and author/editor workflows. +4. Run `npm run qa`, `npm run build`, `npm run verify:dist`, and optional browser suites against an appropriately configured Preview environment. +5. Document limitations, real test evidence, rollback steps and relevant deployment environment without exposing secrets or personal account data. +6. Mark incomplete builds **pre-release**. Do not call a build Production-ready based only on mocked QA or GitHub Pages status. + +## CI limitations + +`.github/workflows/ci.yml` uses intentionally fake Supabase *publishable* configuration and a non-resolvable example domain. It only tests that sources and build output satisfy static/mock checks. The job must not execute SQL, send writes to a live Supabase instance, or upload the build artifact for deployment. + +**Different hosts, different features:** GitHub Pages can host static pages, but **Vercel** is used by this repository's configuration for `/articles`, `/articles/:slug`, and `/sitemap.xml`. A successful GitHub Pages deployment is not verification of those serverless functions. From 1b2ebf53cf59f88fe27625f1213e710c29c41e25 Mon Sep 17 00:00:00 2001 From: Kian Khayat <251517302+cianium@users.noreply.github.com> Date: Tue, 20 Oct 2026 16:03:41 +0330 Subject: [PATCH 4/4] fix(ci): avoid false positives in generated config comments --- .github/workflows/ci.yml | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 48c5324..a93169b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -28,15 +28,15 @@ jobs: steps: - name: Check out repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Set up Node.js - uses: actions/setup-node@v4 + uses: actions/setup-node@v5 with: node-version: '22' - name: Set up Python - uses: actions/setup-python@v5 + uses: actions/setup-python@v6 with: python-version: '3.11' @@ -51,9 +51,8 @@ jobs: - name: Confirm CI placeholders were used run: | - grep -F 'https://ci-placeholder.supabase.co' dist/assets/runtime-config.js - grep -F 'sb_publishable_ci_placeholder_not_a_real_key' dist/assets/runtime-config.js - if grep -R -l -E '(sb_secret_|service_role)' dist/assets/runtime-config.js; then - echo 'Unexpected privileged credential marker in generated config' - exit 1 - fi + grep -Fq 'https://ci-placeholder.supabase.co' dist/assets/runtime-config.js + grep -Fq 'sb_publishable_ci_placeholder_not_a_real_key' dist/assets/runtime-config.js + # Avoid scanning harmless warning comments for the words "service_role": + # tools/dist-qa.mjs already validates credential assignment values. + echo 'Verified fake build configuration; artifact is not deployable.'