Files
poli0981andClaude Opus 5.5 b2eb8236b4 chore(repo): enter maintenance mode — policy, auto-triage, issue forms, badges
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>
2026-11-17 10:53:40 +07:00

202 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.