YTDescGen is feature-complete; from 1.6.0 on it is maintained, not extended. Still accepted: scheduled dependency updates; fixes for high or critical CVEs and serious runtime issues; major language / runtime / framework upgrades; bug, UI/UX and accessibility fixes, and options added to or removed from the app's lists when people really need them; translation fixes; Cloudflare / Worker changes the platform forces and website incidents. - README: status, CI, Qodana and SonarCloud badges; a Project status section; Contributing and the Roadmap row follow it. - CONTRIBUTING: a Maintenance mode section, Option requests, issue and pull request rules, What We Want / Don't Want. - SECURITY, MAINTAINERS, CLAUDE.md: the policy where each one needs it. - ROADMAP: status block, a Maintenance mode section, Phase 5 and the backlog frozen. FEATURES: the extension points are frozen. - Issue forms: Feature request removed; Option request and Translation or wording fix added; Bug report and Accessibility barrier now carry the `needs-triage` label (`triage` never existed). config.yml points feature ideas at Discussions → Ideas. The PR template gains a Scope checklist. - maintenance-triage.yml closes, with a bilingual comment and the `out-of-scope` label, feature issues and `feat:` pull requests from outside contributors (scopes options, a11y and i18n stay open) and anything labelled `out-of-scope`. pull_request_target without checkout; listed under zizmor's dangerous-triggers ignore with the reason. Labels created on the repository: out-of-scope, needs-triage, i18n, option-request. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
202 lines
19 KiB
Markdown
202 lines
19 KiB
Markdown
# CLAUDE.md — YTDescGen
|
||
|
||
## Project Overview
|
||
|
||
**YTDescGen** generates YouTube titles, descriptions and tags for Gameplay No Commentary channels, in eight languages, with profiles (channel), presets (game) and templates (whole form) to skip repeated data entry.
|
||
|
||
- **Web app**: <https://ytgenerator.stream> — a Cloudflare Worker (Turnstile gate + static build), deployed by Cloudflare Workers Builds on every push to `main`. See [docs/HOSTING.md](docs/HOSTING.md).
|
||
- **Desktop** (Windows / macOS / Linux) and **Android** apps: Tauri 2, released from signed tags.
|
||
- **Repository**: `github.com/poli0981/youtube-generator` · **License**: Apache-2.0 (`LICENSE`, `NOTICE`, REUSE-compliant).
|
||
- **Maintainer**: poli0981 (SkullMute). Contacts by purpose: see `src/config/about.ts` and README.
|
||
|
||
**Status: maintenance mode** (since v1.6.0). Don't propose new features. Every change must fall under the policy in [`CONTRIBUTING.md` → Maintenance mode](CONTRIBUTING.md#maintenance-mode):
|
||
|
||
- dependency updates on the regular schedule;
|
||
- security fixes (a CVE rated high or critical, a serious runtime issue);
|
||
- major language, runtime or framework upgrades;
|
||
- bug, UI/UX and accessibility fixes, and adding or removing an option in one of the app's lists (stores, platforms, genres, video types, content warnings, tech notes, GPUs, upscaler / frame-gen modes) when people really need it;
|
||
- translation fixes (wording that doesn't fit a culture or region, misleading spelling);
|
||
- Cloudflare / Worker changes the platform forces, website incidents.
|
||
|
||
`.github/workflows/maintenance-triage.yml` closes out-of-scope issues and pull requests (label `out-of-scope`); `feat(options)`, `feat(a11y)` and `feat(i18n)` pull requests stay open.
|
||
|
||
## Tech Stack
|
||
|
||
| Layer | Technology |
|
||
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| UI | React 19, TypeScript 7 (strict), Radix primitives (`radix-ui`), Motion (LazyMotion), cmdk, sonner, lucide-react + simple-icons |
|
||
| Build | Vite 8 (Rolldown); config imports need `.ts` extensions; Node 26 (`.node-version`) |
|
||
| Type checking | TypeScript 7 `tsc` (`@typescript/native`); `typescript` is an npm alias for `@typescript/typescript6`, the 6.0 API typescript-eslint loads |
|
||
| Styling | Tailwind CSS 4, CSS-first `@theme` tokens in `src/styles/globals.css` |
|
||
| State | Zustand 5 + `persist` (localStorage) — the only store on every platform |
|
||
| Routing | React Router 7 — `BrowserRouter` on the web, `HashRouter` in Tauri |
|
||
| i18n | i18next + react-i18next, 8 locales (en, vi, ja, es, ko, zh, pt-BR, id); `en` bundled, others lazy |
|
||
| Desktop / Android | Tauri 2 (Rust) — see `src-tauri/` |
|
||
| Web hosting | Cloudflare Workers (`worker/`, `wrangler.jsonc`), Turnstile, Web Analytics |
|
||
| Tests | Vitest (node environment; Worker tests included) |
|
||
| Quality | ESLint, Prettier, knip, coverage thresholds, bundle budget, licence allow-list, copyright years, REUSE, actionlint/zizmor, cargo fmt/clippy/deny, SonarCloud (CI-based), Qodana (JS + Rust) |
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
src/
|
||
App.tsx, main.tsx # router, providers, start-up effects
|
||
engine/ # pure template engine — no React, no DOM
|
||
template-renderer.ts # renderAll(): title + description + tags
|
||
title-builder.ts # titles (badge position, separator, case, order)
|
||
title-variants.ts # alternative title shapes
|
||
description-builder.ts # the description, block by block
|
||
tag-generator.ts # tag pools, YouTube's tag length count, trimming
|
||
timeline-parser.ts # timestamps → chapters, YouTube's chapter rules
|
||
channel-phrase.ts # drops "on {{channel}}" when there is no channel name
|
||
types.ts # GeneratorInput, CONTENT_WARNINGS, TECH_NOTES, option lists
|
||
rig-block.ts, limits.ts, social-post-builder.ts, pinned-comment-builder.ts, playlist-builder.ts,
|
||
endings-format.ts, graphics-vendor.ts, upscale.ts (upscaled in the editor: one rule for title,
|
||
description and form)
|
||
config/ # static data: video types, genres, platforms (stores),
|
||
# social fields/platforms, GPU catalog, rig fields,
|
||
# content-warning-groups / tech-note-groups (editor groups),
|
||
# library-fields (profile/preset/per-video field lists),
|
||
# contact-emails (purpose words), brand (copyright years),
|
||
# legal, about, field limits, Vietnamese banks, …
|
||
store/ # Zustand stores; each exports its version + migrate fn
|
||
editor-store.ts # the draft (EditorData, migrateEditorState, editorDataOf)
|
||
profile-store.ts, preset-store.ts, template-store.ts, history-store.ts
|
||
settings-store.ts + settings-heal.ts # settings; healed on every load
|
||
log-store.ts, pending-invalid-store.ts # typed-but-invalid values, for Strict Mode
|
||
utils/
|
||
backup/ # backup format v2, detect, sanitize, restore (+undo),
|
||
# collect, desktop auto-backups, start-up recovery
|
||
library-apply.ts # apply profile/preset/template, next part, start over
|
||
store-paste.ts # store links pasted anywhere
|
||
native.ts # typed bridge to the Tauri commands
|
||
file-ops.ts # save/open text files on every platform
|
||
validation.ts, url-extractors.ts, log-storage.ts, …
|
||
hooks/, components/, pages/, i18n/, styles/
|
||
worker/ # Cloudflare Worker: gate, cookies, headers, rate limits, routing
|
||
build-plugins/ # legal pages at build time; web-only extras
|
||
src-tauri/src/ # lib.rs (plugins, tray), storage.rs (name-only file
|
||
# commands), file_dialog.rs (native Save/Open)
|
||
migration-page/ # moving notice for the old GitHub Pages address (until 2026-11-29)
|
||
tests/ # engine, store, utils, worker, build, i18n, config, hooks, scripts
|
||
scripts/ # locale validation + generator, version sync, Tauri versions,
|
||
# bundle budget, licences/third-party notices, copyright
|
||
# years, brand assets
|
||
docs/ # DEVELOPMENT, HOSTING, ARCHITECTURE, FEATURES, ROADMAP,
|
||
# TECH-SPEC, I18N, PACKAGING, CONTENT-INVENTORY
|
||
i18n/vi/ # Vietnamese: DEVELOPMENT, CONTENT-INVENTORY, DISCLAIMER
|
||
assets/brand/ # logo sources: every icon and the link-preview card come from them
|
||
public/ # static web files (_headers, icons, manifest, 404, robots, sitemap)
|
||
LICENSES/ # license texts for REUSE
|
||
```
|
||
|
||
## Coding Conventions
|
||
|
||
### TypeScript
|
||
|
||
- Strict mode; no `any` — use `unknown` + type guards.
|
||
- Prefer `interface` for object shapes; `as const` for static config arrays.
|
||
- `src/` is typed against `lib` ES2022 — the browsers' floor (Chrome 111, Safari 16.4, Firefox 114), because Vite never polyfills. Don't reach for newer built-ins in the app without raising that floor; tests, scripts, worker and build plugins get ES2025 (`tsconfig.check.json`). `target` is ES2025 (ES2026 waits for TypeScript 7.1).
|
||
- Erasable syntax only (`erasableSyntaxOnly`, `verbatimModuleSyntax`): no enums, namespaces or parameter properties; `import type` for types.
|
||
- React 19: `ref` is an ordinary prop — no `forwardRef`.
|
||
- Regexes must stay linear (SonarCloud S8786): no unbounded quantifier that can restart inside its own run (`\s+$`, a leading `\s+` in an unanchored pattern, `\s*` next to `\s*`) — trim first, anchor, bound the run, or use a loop.
|
||
|
||
### React
|
||
|
||
- Function components only; shared logic in `use*` hooks.
|
||
- Pages are lazy-loaded; keep the Editor (landing page) light — the **initial load budget is 280 KB gzip** (`npm run check:bundle`), no chunk over 500 KB raw.
|
||
- Read store slices with selectors; avoid prop drilling beyond two levels.
|
||
|
||
### Naming
|
||
|
||
- Files: `kebab-case.ts`, components `PascalCase.tsx`; stores `use[Name]Store`; constants `UPPER_SNAKE_CASE`.
|
||
|
||
### Styling
|
||
|
||
- Tailwind utilities and the design tokens (`bg-surface-1`, `text-text-muted`, `accent`, …) — no hard-coded colours, no inline styles.
|
||
- Dark by default, light via class; touch targets grow on coarse pointers (`pointer-coarse:`), nothing clickable under 24 px.
|
||
- Contrast is WCAG AA in both themes and `tests/styles/contrast.test.ts` checks every token: text tokens on surfaces, white text only on the `*-solid` fills (`bg-accent-solid`, `bg-danger-solid`), never on `bg-accent`.
|
||
- Focus: the global `:focus-visible` outline; a control that swaps it for a ring uses `outline-hidden` (stays visible in forced colours), not `outline-none`.
|
||
- Watch Tailwind 4 specificity: a base `inline-flex` beats a plain `hidden` — wrap responsive visibility in an element.
|
||
|
||
### i18n
|
||
|
||
- Every user-visible string goes through `t()`; UI strings in `ui.json`, generated text in `templates.json`.
|
||
- New keys go into **all 8 locales** and `_schema.json`; `npm run validate:locales` must pass.
|
||
- No plural suffixes (`_one`/`_other`) — the key sets must match across locales; write count-neutral text.
|
||
|
||
### State
|
||
|
||
- Stores are persisted with Zustand `persist`; a shape change bumps the store's exported version and adds a step to its exported migrate function (backups replay the same steps). Steps must be idempotent.
|
||
- Settings are healed on every load (`healSettings`); consent and UI-state fields are device-local and never exported.
|
||
|
||
### Engine
|
||
|
||
- Pure functions only: typed input → string. No React, clipboard, storage or DOM; the year and other environment values come from the caller.
|
||
|
||
## Key Design Decisions
|
||
|
||
1. **The engine is framework-agnostic** (`src/engine/` has no React imports).
|
||
2. **i18n covers the UI and the generated text**, as separate namespaces.
|
||
3. **Profiles vs presets vs templates**: profile = channel (rarely changes), preset = game (reused across parts), template = the whole form. The field lists live in `src/config/library-fields.ts`.
|
||
4. **Tags are generated**, then trimmed to YouTube's own length count.
|
||
5. **Your data stays on your device.** localStorage is the only store; backups are files the user controls (plus automatic backups in the desktop app's data folder).
|
||
6. **The desktop webview never names a path**: Rust commands take file names under the app data folder or open the native dialog themselves. Blocking work in an `async` command (a dialog, file I/O) goes through `tauri::async_runtime::spawn_blocking` — SonarCloud flags it otherwise (`rust:S7493`).
|
||
7. **The web app is gated** by Turnstile, verified server-side in the Worker; the gate fails open if its secret is missing.
|
||
|
||
## Development Commands
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev # Vite dev server (http://localhost:5173)
|
||
npm run build # typecheck + production build
|
||
npm run test:run # all tests (npm test = watch mode)
|
||
npm run test:coverage # with coverage thresholds
|
||
npm run typecheck # src
|
||
npm run typecheck:all # src + tests + scripts + worker + build plugins
|
||
npm run lint && npm run format:check
|
||
npm run knip # unused files/exports/dependencies
|
||
npm run validate:locales
|
||
npm run check:bundle # after build: initial load / chunk budget
|
||
npm run check:licenses # licence allow-list + THIRD_PARTY_NOTICES in sync (generate:third-party fixes)
|
||
npm run check:copyright # NOTICE, REUSE.toml, installer copyright = HEAD's year (update:copyright fixes)
|
||
npm run check:version # the six version fields agree
|
||
npm run check:tauri # @tauri-apps/* and tauri crates on the same major.minor
|
||
npm run cf:dev # wrangler dev (copy .dev.vars.example to .dev.vars — test keys only)
|
||
npm run cf:check # wrangler deploy --dry-run
|
||
npm run tauri:dev # desktop app against the dev server
|
||
npm run tauri:build # desktop installers
|
||
npm run generate:locale # scaffold a new locale folder from en (-- --lang xx)
|
||
npm run generate:brand # favicon, PWA icons, link-preview card from assets/brand/
|
||
# src-tauri/: cargo fmt --check · cargo clippy --all-targets --locked -- -D warnings · cargo test
|
||
```
|
||
|
||
## Git Workflow
|
||
|
||
- `main` only: feature branches (`feat/…`, `fix/…`, `docs/…`, `chore/…`) → PR → `main`. Every merge to `main` deploys the web app.
|
||
- Commit and PR-title format: `type(scope): message` (`feat`, `fix`, `refactor`, `docs`, `test`, `ci`, `chore`) — CI checks PR titles, and the message must start with a lower-case letter (`feat(editor): warnings for AI…`, not `feat(editor): AI…`).
|
||
- Commits and release tags are GPG-signed; never bypass signing or hooks.
|
||
- Required checks: `check`, `dependency-review`, `workflow-lint`, `reuse`, `pr-title`.
|
||
|
||
## Releases
|
||
|
||
- Bump the version in all six places: `package.json`, `package-lock.json` (×2), `src-tauri/tauri.conf.json`, `src-tauri/Cargo.toml`, `src-tauri/Cargo.lock` (`npm run check:version`), and add a `CHANGELOG.md` entry.
|
||
- Push a signed tag `vX.Y.Z` → the release workflows verify, build the desktop and Android artifacts and create a **draft** release. The maintainer publishes it.
|
||
|
||
## Important Notes for Claude Code
|
||
|
||
- Run the gates before committing: `typecheck`, `typecheck:all`, `lint`, `format:check`, `test:run`, `knip`, `validate:locales`, `check:version`, `check:tauri`, `check:licenses`, `check:copyright`, `build` + `check:bundle`; `cargo fmt/clippy/test` when `src-tauri/` changes. In the first commit of a new year, `npm run update:copyright` (CI's `check:copyright` fails until then). A dependency change can make `check:licenses` fail: `npm run generate:third-party` rewrites the notices, and a new direct crate in `src-tauri/Cargo.toml` that isn't Tauri's needs its license in `OTHER_CRATES` (`scripts/lib/third-party.ts`).
|
||
- New contact-email purpose words: `src/config/contact-emails.ts` (lower-case; a test keeps every locale's example address valid).
|
||
- New language: follow `docs/I18N.md` (register it, both namespaces, tag pools, `channel-phrase.ts` patterns, browser detection).
|
||
- New genre: `src/config/genres.ts` + its tag pool in `src/engine/tag-generator.ts` (a test keeps them in sync).
|
||
- New video type: `src/config/video-types.ts` + every `templates.json` (titles, intros, pinned-comment greetings).
|
||
- New content warning / tech note: the id in `CONTENT_WARNINGS` / `TECH_NOTES` (`src/engine/types.ts`), a group in `src/config/content-warning-groups.ts` / `tech-note-groups.ts`, the editor label (`ui.json`) and description line (`templates.json`) in all 8 locales and `_schema.json` — tests fail on any gap — and the row in `docs/CONTENT-INVENTORY.md` (+ vi). Don't repeat a fact that has its own field (language patch, game version, difficulty, the Video settings upscaler).
|
||
- New store platform: `src/config/platforms.ts` (URL pattern, `tagName`), optionally a name extractor in `src/utils/url-extractors.ts`.
|
||
- New upscaler / frame-gen option: the id in `src/config/graphics-settings.ts`, the vendor's list in `src/engine/graphics-vendor.ts`, the editor label (`editor.upscaleQuality.<vendor>` / `editor.frameGenMultiplier.<vendor>`, `ui.json`) and the description label (`description.graphics.upscale|frameGen.<vendor>`, `templates.json`) in all 8 locales and `_schema.json` — `tests/engine/graphics-vendor.test.ts` fails on a gap. A new id only widens the lists (no store bump); a new field does need one.
|
||
- UI changes follow the accessibility checklist in `ACCESSIBILITY.md` (#for-contributors): keyboard, names via `Field` / `IconButton`, announced errors, tokens only, reduced motion, 24 px targets. Generated text gets `lang` (the output language); pages name themselves with `useDocumentTitle`, which `RouteAnnouncer` reads out. Update ACCESSIBILITY.md (+ `docs/i18n/vi/`) when what it promises changes.
|
||
- Never commit `note.txt`, `warning.txt` or `__pycache__/`; never put real secrets in files (`.dev.vars` holds Cloudflare's public Turnstile test keys only).
|
||
- SonarCloud (project `poli0981_youtube-generator`) is CI-based: the `sonarcloud` job in `ci.yml` scans every PR from this repository and every push to `main`, with the coverage from `check`; settings in `sonar-project.properties`; Automatic Analysis is off. Keep it at 0 open issues and the quality gate (Sonar way: A ratings, reviewed hotspots, ≤ 3 % duplication, ≥ 80 % coverage on new code) green — the job fails with the gate. Coverage covers what `coverage.include` in `vitest.config.ts` lists (the logic layers); everything else is in `sonar.coverage.exclusions`, because a file missing from the LCOV report counts as 0 % — a new source folder goes into one list or the other. The version passed to the scanner starts each release's new-code period. Fork and Dependabot PRs skip the scan (no `SONAR_TOKEN`). Check a PR with `https://sonarcloud.io/api/issues/search?componentKeys=poli0981_youtube-generator&pullRequest=<n>&resolved=false` and its gate with `https://sonarcloud.io/api/qualitygates/project_status?projectKey=poli0981_youtube-generator&pullRequest=<n>`. Workflows install with `npm ci --ignore-scripts` and call local binaries (`npm run …`), never `npx` for a package that isn't installed.
|
||
- Qodana (`.github/workflows/qodana.yml`) runs on every PR and push to `main`: job `typescript` is Qodana for JS in native mode (`qodana.yaml`, Cloud project `yt-ts-js`, secret `QODANA_TOKEN_TS_JS`), job `rust` is Qodana for Rust, Early Access, in Docker on `src-tauri/` (`src-tauri/qodana.yaml`, project `yt-rust`, secret `QODANA_TOKEN_RUST`). Both gate on zero problems: fix a finding, or exclude it in the `qodana.yaml` with a comment saying why. Both skip without their token (Dependabot and fork PRs). It needs an Ultimate licence (currently the trial): when it lapses both jobs fail at the licence check.
|
||
- TypeScript bumps may be manual: `@typescript/native` (`npm:typescript@^7`) and `typescript` (`npm:@typescript/typescript6@^6`) are npm aliases Dependabot may not follow. Stop the dev server before `npm ci` on Windows — it locks native modules (EPERM).
|
||
- The Cloudflare dashboard, publishing releases and repository settings are the maintainer's; ask before touching them.
|