From cb61982c1a76316cb4906ea3f7c359a210d1cafa Mon Sep 17 00:00:00 2001 From: Sean Grace <107606977+8GSean@users.noreply.github.com> Date: Mon, 15 Jun 2026 09:47:08 +0300 Subject: [PATCH] feat: add deploy module with CLI-first guidance and deploy FAQ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a /learn deploy module that helps learners choose a deployment tool (GitHub Pages / Cloudflare / Render / Vercel), understand the free-tier trade-offs, and run the commands themselves. - deploy.md: diagnose -> decision tree -> account creation -> cost awareness -> contribute-to-FAQ loop - cli-first.md: shared reference — prefer official CLIs over dashboards - deploy-faq.md: course-scoped FAQ, grown via student PRs - learn.md / CLAUDE.md: wire up routing and module registry - FAQ.md: cross-link to the deploy FAQ for discoverability Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/commands/learn.md | 2 + .claude/commands/learn/cli-first.md | 37 ++++++++++ .claude/commands/learn/deploy.md | 100 ++++++++++++++++++++++++++++ CLAUDE.md | 2 + FAQ.md | 2 + courses/ai-dev/deploy-faq.md | 67 +++++++++++++++++++ 6 files changed, 210 insertions(+) create mode 100644 .claude/commands/learn/cli-first.md create mode 100644 .claude/commands/learn/deploy.md create mode 100644 courses/ai-dev/deploy-faq.md diff --git a/.claude/commands/learn.md b/.claude/commands/learn.md index 0b51d63..c702d5a 100644 --- a/.claude/commands/learn.md +++ b/.claude/commands/learn.md @@ -71,6 +71,7 @@ Create `~/skill-tutor-tutorials/learner_profile.md` with their answers. | $ARGUMENTS = "status" | Read `.claude/commands/learn/status.md` | | $ARGUMENTS = "slides" or "slides [lesson]" | Read `.claude/commands/learn/slides.md` | | $ARGUMENTS = "project" | Read `.claude/commands/learn/project.md` | +| $ARGUMENTS = "deploy" | Read `.claude/commands/learn/deploy.md` | | $ARGUMENTS = "export" | Read `.claude/commands/learn/export.md` | | $ARGUMENTS = "import" or "import [path]" | Read `.claude/commands/learn/import.md` | | $ARGUMENTS empty | Read `.claude/commands/learn/resume.md` | @@ -101,5 +102,6 @@ Create `~/skill-tutor-tutorials/learner_profile.md` with their answers. | socratic / הדרך אותי | Switch to socratic mode (question-led discovery) | | slides | Read `.claude/commands/learn/slides.md` — verbatim slide reading mode | | project | Read `.claude/commands/learn/project.md` — final project mode | +| deploy | Read `.claude/commands/learn/deploy.md` — pick a deploy tool (GitHub Pages / Cloudflare / Render / Vercel) | | export | Read `.claude/commands/learn/export.md` — export all learner data to a ZIP | | import | Read `.claude/commands/learn/import.md` — import learner data from a ZIP | diff --git a/.claude/commands/learn/cli-first.md b/.claude/commands/learn/cli-first.md new file mode 100644 index 0000000..e78566f --- /dev/null +++ b/.claude/commands/learn/cli-first.md @@ -0,0 +1,37 @@ +# CLI-First Reference + +*Shared principle. Any module may reference this as "follow cli-first".* + +When guiding a learner through any setup, deploy, or repo operation — **prefer the command line over clicking dashboards.** The goal is for the learner to understand what is happening, build a reusable muscle, and end up with a reproducible workflow. + +## Rules + +1. **Show the command, then explain it.** Never give a command without one line on what it does and why. +2. **Prefer official CLIs** over web UIs: + - GitHub → `gh` (`gh repo create`, `gh pr create`, `gh auth login`) + - Cloudflare → `wrangler` (`wrangler deploy`, `wrangler pages deploy`, `wrangler login`) + - Render → `render` CLI or a `render.yaml` blueprint committed to the repo + - Vercel → `vercel`, Netlify → `netlify` + - Git → plain `git` (`git init`, `git add`, `git commit`, `git push`) +3. **Use the UI only when the CLI genuinely can't do it** — e.g. first-time OAuth login, adding a payment method, or a one-time account verification. Say explicitly "this step is UI-only because…". +4. **Reproducibility:** prefer commands and committed config files (`wrangler.toml`, `render.yaml`, `.github/workflows/`) over manual dashboard settings, so the setup survives a fresh clone. +5. **Windows note:** the learner is likely on PowerShell. Give PowerShell-safe commands (`$env:VAR`, not `export`). Most of these CLIs are cross-platform via `npm i -g` or `winget`. +6. **Secrets never go in the repo or the command history in plain text.** Use the platform's secret store (`wrangler secret put`, `gh secret set`, Render env vars) — and explain why. + +## Mini cheat sheet to surface when relevant + +```bash +# GitHub +gh auth login # one-time login (opens browser — UI-only step) +gh repo create my-app --public --source=. --push + +# Cloudflare Workers / Pages +npm i -g wrangler +wrangler login # one-time login (browser) +wrangler deploy # deploy a Worker +wrangler pages deploy ./dist # deploy a static build to Pages +wrangler secret put API_KEY # store a secret safely + +# Git basics +git init && git add . && git commit -m "init" && git push +``` diff --git a/.claude/commands/learn/deploy.md b/.claude/commands/learn/deploy.md new file mode 100644 index 0000000..0ace28c --- /dev/null +++ b/.claude/commands/learn/deploy.md @@ -0,0 +1,100 @@ +# Deploy Module — איזה כלי פריסה לבחור + +*Loaded when /learn is called with "deploy" argument, or when a learner asks how/where to deploy a project.* + +Respond in `session.language` throughout (default Hebrew). Address the learner using `session.address`. Follow **cli-first** — read `.claude/commands/learn/cli-first.md` and prefer commands over dashboards, always showing the command + a one-line "why". + +The job of this module is **not** to deploy for them silently — it is to help them *choose the right tool, understand why, and run the commands themselves* so they learn by doing. + +--- + +## Core Principles (state these once, briefly, at the start) + +1. בונים פרויקטים אמיתיים — לומדים תוך כדי deploy. +2. מעדיפים כלים חינמיים, ומכירים את המגבלות של ה-free tier. +3. מעדיפים CLI על פני לחיצות בדאשבורד (follow cli-first). +4. פותחים חשבון חדש **רק כשבאמת צריך** — לא מראש. +5. תמיד מסבירים *למה* בחרנו בכלי. + +--- + +## Step 1 — Read the FAQ first + +Read `courses/ai-dev/deploy-faq.md`. If the learner's question already has an answer there, lead with it (and mention it came from the shared FAQ). This rewards the contribution loop. + +--- + +## Step 2 — Diagnose (3 questions, ask together) + +Do **not** guess the platform from project type alone. Ask: + +1. הפרויקט הוא רק frontend (HTML/CSS/JS, או build של React/Vite) בלי שרת? +2. הוא קורא ל-LLM / API עם מפתח סודי, או צריך בסיס נתונים? +3. הוא צריך שרת שרץ כל הזמן — websockets, תהליך ברקע, job מתוזמן, או Postgres? + +The most important branch for this course: **question 2.** A static site cannot hide an API key — anything in the browser is visible. So an AI project that *looks* static (a React chat UI calling Claude) actually needs a tiny server to hold the key. Make this explicit when it applies. + +--- + +## Step 3 — Decision tree + +| מצב | המלצה | למה | +|-----|--------|-----| +| סטטי בלבד, בלי סודות ובלי שרת | **GitHub Pages** | חינם, אפס תחזוקה, deploy ישירות מה-repo. ברירת המחדל תמיד. | +| סטטי + מפתח API / LLM / DB קל | **Cloudflare Workers + Wrangler** | Worker קטן מחזיק את המפתח (`wrangler secret put`) ומעביר את הבקשה. KV/D1 לנתונים. free tier נדיב. | +| צריך build/preview deploys, טפסים, או DX של אתר סטטי "פלוס" | **Cloudflare Pages** (או Netlify) | עדיין חינם, build אוטומטי, preview לכל PR. | +| שרת תמידי — websockets, Postgres, job ברקע | **Render** | תומך בשרת ארוך-טווח. **אזהרה:** free tier נרדם אחרי 15 דק' (cold start ~30 שניות). | +| Next.js עם SSR, רוצים zero-config | **Vercel / Netlify** | הכי קל ל-Next. **אבל:** vendor lock-in ו-hobby tier מוגבל לשימוש לא-מסחרי. | + +**כלל הברירת מחדל:** אם זה סטטי — תמיד GitHub Pages, אלא אם סיבה ספציפית שוללת אותו. + +When recommending, give: +- שם הכלי + משפט "למה", +- מגבלת ה-free tier הרלוונטית, +- הפקודות הראשונות (follow cli-first), בלי לפתוח חשבון עד שבאמת צריך. + +--- + +## Step 4 — Account creation (only when needed) + +פותחים חשבון רק כשמגיעים לשלב שדורש אותו, לפי הסדר: + +1. **GitHub** — תמיד (כבר יש להם מהקורס). +2. **Cloudflare** — רק אם בוחרים Workers/Pages. אין צורך בכרטיס אשראי ל-free tier. +3. **Render** — רק אם צריך שרת תמידי. +4. **Vercel / Netlify** — רק אם באמת נדרש (Next SSR). + +לכל חשבון: ציין שזה צעד UI-only חד-פעמי (OAuth login), והמשך משם ב-CLI. + +--- + +## Step 5 — Cost & free-tier awareness + +לפני שמסיימים, ודא שהלומד יודע את המגבלה של מה שבחר (זה מתחבר ל-checklist של פרויקט הגמר — חישוב עלות): + +- **GitHub Pages:** repo ציבורי, ~1GB, 100GB תעבורה/חודש. +- **Cloudflare Workers:** ~100K בקשות/יום ב-free. +- **Render free:** נרדם אחרי 15 דק' חוסר פעילות. +- **Vercel/Netlify hobby:** לא-מסחרי, מגבלות build/bandwidth. + +אם הפרויקט קורא ל-LLM — הזכר את עלות ה-API עצמו (זה נפרד מעלות ה-hosting). + +--- + +## Step 6 — Contribute to the FAQ (PR via gh) + +If the learner hit a snag **not** already in `deploy-faq.md` and solved it, offer: + +> "פתרת בעיה חדשה — רוצה להוסיף אותה ל-FAQ המשותף? זה תרגול אמיתי של git + PR, ותעזור לתלמידים הבאים." + +If yes, follow **cli-first** and walk them through it (let them run the commands — explain each): + +```bash +git checkout -b faq/ +# הוסף את השאלה + התשובה לסעיף המתאים ב-courses/ai-dev/deploy-faq.md +git add courses/ai-dev/deploy-faq.md +git commit -m "faq: " +gh pr create --fill +``` + +Draft the FAQ entry text for them (question + concise answer + command if relevant), but let *them* run the git/PR commands so they practice the workflow. If `gh` isn't authenticated, that's the one UI-only step (`gh auth login`). diff --git a/CLAUDE.md b/CLAUDE.md index 9337a5f..6513686 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,6 +21,8 @@ | Slides | `.claude/commands/learn/slides.md` | קריאה מילה במילה מסקריפטים, viewer אינטראקטיבי, TTS אוטומטי | | Export | `.claude/commands/learn/export.md` | ייצוא כל נתוני התלמיד ל-ZIP — גיבוי/מעבר למכשיר אחר | | Import | `.claude/commands/learn/import.md` | ייבוא נתוני תלמיד מ-ZIP — החלפה מלאה או הוספה בלבד | +| Deploy | `.claude/commands/learn/deploy.md` | בחירת כלי פריסה (GitHub Pages / Cloudflare / Render / Vercel), CLI-first, תרומה ל-FAQ | +| CLI-First (ref) | `.claude/commands/learn/cli-first.md` | עקרון משותף — העדפת CLI על דאשבורד; מודולים אחרים מפנים אליו | סקריפטים תומכים נמצאים ב-`.claude/scripts/` (PowerShell — slide server, HTML generator). diff --git a/FAQ.md b/FAQ.md index 6ca21e1..0537b0f 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,5 +1,7 @@ # שאלות נפוצות — Tov-learn +> **שאלות על פריסה (deploy)?** ראו את ה-FAQ הייעודי: [`courses/ai-dev/deploy-faq.md`](courses/ai-dev/deploy-faq.md) — GitHub Pages, Cloudflare Workers, Render ועוד. + --- ## AntiGravity — עבודה עם פרויקטים diff --git a/courses/ai-dev/deploy-faq.md b/courses/ai-dev/deploy-faq.md new file mode 100644 index 0000000..3831e70 --- /dev/null +++ b/courses/ai-dev/deploy-faq.md @@ -0,0 +1,67 @@ +# Deploy FAQ — שאלות נפוצות על פריסה + +*נקרא על ידי מודול `deploy`. תלמידים מוסיפים שאלות חדשות דרך PR (ראה תחתית הקובץ).* + +כל ערך: שאלה, תשובה קצרה, ופקודה אם רלוונטי. + +--- + +## כללי + +### האם אפשר להחביא מפתח API באתר סטטי? +**לא.** כל מה שרץ בדפדפן גלוי למשתמש — כולל מפתחות. אם הפרויקט קורא ל-LLM או לכל API עם מפתח, צריך שכבת שרת קטנה (Cloudflare Worker) שמחזיקה את המפתח ומעבירה את הבקשה. האתר הסטטי קורא ל-Worker, ה-Worker קורא ל-API. + +### מתי GitHub Pages ומתי משהו אחר? +GitHub Pages = אתר סטטי בלבד (HTML/CSS/JS, build של React/Vite), בלי שרת ובלי סודות. ברגע שצריך מפתח, DB, או לוגיקת שרת — עוברים ל-Cloudflare Workers. שרת ארוך-טווח (websockets, Postgres, job ברקע) — Render. + +--- + +## GitHub Pages + +### האתר עלה אבל הקבצים (CSS/JS) לא נטענים — מסך לבן +ב-build של Vite/React הנתיבים מוחלטים (`/assets/...`) אבל Pages מגיש מתת-נתיב (`/repo-name/`). הוסיפו `base: '/repo-name/'` ל-`vite.config.js` ובנו מחדש. + +### איך מפרסמים build של Vite ל-Pages דרך CLI? +```bash +npm run build +npx gh-pages -d dist # או GitHub Action שמפרסם את dist אוטומטית +``` + +--- + +## Cloudflare Workers / Wrangler + +### איך שומרים מפתח API ב-Worker בלי לחשוף אותו? +```bash +wrangler secret put ANTHROPIC_API_KEY # נשמר מוצפן בצד Cloudflare, לא ב-repo +``` +בקוד ניגשים אליו דרך `env.ANTHROPIC_API_KEY`. אף פעם לא בתוך הקוד או ב-git. + +### חייבים כרטיס אשראי כדי לפתוח חשבון Cloudflare? +לא ל-Workers/Pages ברמת ה-free. פותחים חשבון רק כשבאמת מגיעים לשלב פריסה. + +### שגיאת CORS כשהאתר הסטטי קורא ל-Worker +הוסיפו ל-Worker את כותרות ה-CORS (`Access-Control-Allow-Origin`) וטפלו בבקשת `OPTIONS` (preflight). + +--- + +## Render + +### השירות "נרדם" ולוקח 30 שניות לענות בבקשה הראשונה +ה-free tier של Render משבית שירות אחרי 15 דקות חוסר פעילות והבקשה הבאה מעירה אותו (cold start). תקין ללמידה — לא לפרודקשן אמיתי. + +--- + +## תרומה ל-FAQ + +נתקלתם בבעיה שלא מופיעה כאן ופתרתם? הוסיפו ערך — זה תרגול אמיתי של git + PR: + +```bash +git checkout -b faq/short-topic +# הוסיפו את השאלה והתשובה לסעיף המתאים +git add courses/ai-dev/deploy-faq.md +git commit -m "faq: <נושא קצר>" +gh pr create --fill +``` + +מודול ה-deploy יציע לכם לעשות את זה אוטומטית כשאתם פותרים בעיה חדשה.