Code Review Graph + Docs + Config

2026-08-10 15:15:19 +02:00
parent 603c2b332c
commit ee063aa460
26 changed files with 10420 additions and 3 deletions
@@ -0,0 +1,37 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash",
+      "Write",
+      "WebFetch",
+      "WebSearch",
+      "Edit"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "code-review-graph update --skip-flows",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "code-review-graph status",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
@@ -0,0 +1,27 @@
+---
+name: Debug Issue
+description: Systematically debug issues using graph-powered code navigation
+---
+
+## Debug Issue
+
+Use the knowledge graph to systematically trace and debug issues.
+
+### Steps
+
+1. Use `semantic_search_nodes` to find code related to the issue.
+2. Use `query_graph` with `callers_of` and `callees_of` to trace call chains.
+3. Use `get_flow` to see full execution paths through suspected areas.
+4. Run `detect_changes` to check if recent changes caused the issue.
+5. Use `get_impact_radius` on suspected files to see what else is affected.
+
+### Tips
+
+- Check both callers and callees to understand the full context.
+- Look at affected flows to find the entry point that triggers the bug.
+- Recent changes are the most common source of new issues.
+
+## Token Efficiency Rules
+- ALWAYS start with `get_minimal_context(task="<your task>")` before any other graph tool.
+- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient.
+- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens.
@@ -0,0 +1,28 @@
+---
+name: Explore Codebase
+description: Navigate and understand codebase structure using the knowledge graph
+---
+
+## Explore Codebase
+
+Use the code-review-graph MCP tools to explore and understand the codebase.
+
+### Steps
+
+1. Run `list_graph_stats` to see overall codebase metrics.
+2. Run `get_architecture_overview` for high-level community structure.
+3. Use `list_communities` to find major modules, then `get_community` for details.
+4. Use `semantic_search_nodes` to find specific functions or classes.
+5. Use `query_graph` with patterns like `callers_of`, `callees_of`, `imports_of` to trace relationships.
+6. Use `list_flows` and `get_flow` to understand execution paths.
+
+### Tips
+
+- Start broad (stats, architecture) then narrow down to specific areas.
+- Use `children_of` on a file to see all its functions and classes.
+- Use `find_large_functions` to identify complex code.
+
+## Token Efficiency Rules
+- ALWAYS start with `get_minimal_context(task="<your task>")` before any other graph tool.
+- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient.
+- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens.
@@ -0,0 +1,28 @@
+---
+name: Refactor Safely
+description: Plan and execute safe refactoring using dependency analysis
+---
+
+## Refactor Safely
+
+Use the knowledge graph to plan and execute refactoring with confidence.
+
+### Steps
+
+1. Use `refactor_tool` with mode="suggest" for community-driven refactoring suggestions.
+2. Use `refactor_tool` with mode="dead_code" to find unreferenced code.
+3. For renames, use `refactor_tool` with mode="rename" to preview all affected locations.
+4. Use `apply_refactor_tool` with the refactor_id to apply renames.
+5. After changes, run `detect_changes` to verify the refactoring impact.
+
+### Safety Checks
+
+- Always preview before applying (rename mode gives you an edit list).
+- Check `get_impact_radius` before major refactors.
+- Use `get_affected_flows` to ensure no critical paths are broken.
+- Run `find_large_functions` to identify decomposition targets.
+
+## Token Efficiency Rules
+- ALWAYS start with `get_minimal_context(task="<your task>")` before any other graph tool.
+- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient.
+- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens.
@@ -0,0 +1,29 @@
+---
+name: Review Changes
+description: Perform a structured code review using change detection and impact
+---
+
+## Review Changes
+
+Perform a thorough, risk-aware code review using the knowledge graph.
+
+### Steps
+
+1. Run `detect_changes` to get risk-scored change analysis.
+2. Run `get_affected_flows` to find impacted execution paths.
+3. For each high-risk function, run `query_graph` with pattern="tests_for" to check test coverage.
+4. Run `get_impact_radius` to understand the blast radius.
+5. For any untested changes, suggest specific test cases.
+
+### Output Format
+
+Provide findings grouped by risk level (high/medium/low) with:
+- What changed and why it matters
+- Test coverage status
+- Suggested improvements
+- Overall merge recommendation
+
+## Token Efficiency Rules
+- ALWAYS start with `get_minimal_context(task="<your task>")` before any other graph tool.
+- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient.
+- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens.
@@ -0,0 +1,38 @@
+<!-- code-review-graph MCP tools -->
+## MCP Tools: code-review-graph
+
+**IMPORTANT: This project has a knowledge graph. ALWAYS use the
+code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
+the codebase.** The graph is faster, cheaper (fewer tokens), and gives
+you structural context (callers, dependents, test coverage) that file
+scanning cannot.
+
+### When to use graph tools FIRST
+
+- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
+- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
+- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
+- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
+- **Architecture questions**: `get_architecture_overview` + `list_communities`
+
+Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
+
+### Key Tools
+
+| Tool | Use when |
+|------|----------|
+| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
+| `get_review_context` | Need source snippets for review — token-efficient |
+| `get_impact_radius` | Understanding blast radius of a change |
+| `get_affected_flows` | Finding which execution paths are impacted |
+| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
+| `semantic_search_nodes` | Finding functions/classes by name or keyword |
+| `get_architecture_overview` | Understanding high-level codebase structure |
+| `refactor_tool` | Planning renames, finding dead code |
+
+### Workflow
+
+1. The graph auto-updates on file changes (via hooks).
+2. Use `detect_changes` for code review.
+3. Use `get_affected_flows` to understand impact.
+4. Use `query_graph` pattern="tests_for" to check coverage.
@@ -4,3 +4,5 @@ node_modules/
 *.log
 storage/
 worker/worker.pid
+# Added by code-review-graph
+.code-review-graph/
@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/Ombrora-YTDLP.iml" filepath="$PROJECT_DIR$/.idea/Ombrora-YTDLP.iml" />
+    </modules>
+  </component>
+</project>
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="MessDetectorOptionsConfiguration">
+    <option name="transferred" value="true" />
+  </component>
+  <component name="PHPCSFixerOptionsConfiguration">
+    <option name="transferred" value="true" />
+  </component>
+  <component name="PHPCodeSnifferOptionsConfiguration">
+    <option name="highlightLevel" value="WARNING" />
+    <option name="transferred" value="true" />
+  </component>
+  <component name="PhpStanOptionsConfiguration">
+    <option name="transferred" value="true" />
+  </component>
+  <component name="PsalmOptionsConfiguration">
+    <option name="transferred" value="true" />
+  </component>
+</project>
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>
@@ -0,0 +1,38 @@
+<!-- code-review-graph MCP tools -->
+## MCP Tools: code-review-graph
+
+**IMPORTANT: This project has a knowledge graph. ALWAYS use the
+code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
+the codebase.** The graph is faster, cheaper (fewer tokens), and gives
+you structural context (callers, dependents, test coverage) that file
+scanning cannot.
+
+### When to use graph tools FIRST
+
+- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
+- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
+- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
+- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
+- **Architecture questions**: `get_architecture_overview` + `list_communities`
+
+Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
+
+### Key Tools
+
+| Tool | Use when |
+|------|----------|
+| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
+| `get_review_context` | Need source snippets for review — token-efficient |
+| `get_impact_radius` | Understanding blast radius of a change |
+| `get_affected_flows` | Finding which execution paths are impacted |
+| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
+| `semantic_search_nodes` | Finding functions/classes by name or keyword |
+| `get_architecture_overview` | Understanding high-level codebase structure |
+| `refactor_tool` | Planning renames, finding dead code |
+
+### Workflow
+
+1. The graph auto-updates on file changes (via hooks).
+2. Use `detect_changes` for code review.
+3. Use `get_affected_flows` to understand impact.
+4. Use `query_graph` pattern="tests_for" to check coverage.
@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "code-review-graph": {
+      "command": "code-review-graph",
+      "args": [
+        "serve"
+      ],
+      "type": "stdio"
+    }
+  }
+}
@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "code-review-graph": {
+      "command": "code-review-graph",
+      "args": [
+        "serve"
+      ],
+      "type": "stdio",
+      "env": []
+    }
+  }
+}
@@ -0,0 +1,38 @@
+<!-- code-review-graph MCP tools -->
+## MCP Tools: code-review-graph
+
+**IMPORTANT: This project has a knowledge graph. ALWAYS use the
+code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
+the codebase.** The graph is faster, cheaper (fewer tokens), and gives
+you structural context (callers, dependents, test coverage) that file
+scanning cannot.
+
+### When to use graph tools FIRST
+
+- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
+- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
+- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
+- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
+- **Architecture questions**: `get_architecture_overview` + `list_communities`
+
+Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
+
+### Key Tools
+
+| Tool | Use when |
+|------|----------|
+| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
+| `get_review_context` | Need source snippets for review — token-efficient |
+| `get_impact_radius` | Understanding blast radius of a change |
+| `get_affected_flows` | Finding which execution paths are impacted |
+| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
+| `semantic_search_nodes` | Finding functions/classes by name or keyword |
+| `get_architecture_overview` | Understanding high-level codebase structure |
+| `refactor_tool` | Planning renames, finding dead code |
+
+### Workflow
+
+1. The graph auto-updates on file changes (via hooks).
+2. Use `detect_changes` for code review.
+3. Use `get_affected_flows` to understand impact.
+4. Use `query_graph` pattern="tests_for" to check coverage.
@@ -0,0 +1,38 @@
+<!-- code-review-graph MCP tools -->
+## MCP Tools: code-review-graph
+
+**IMPORTANT: This project has a knowledge graph. ALWAYS use the
+code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
+the codebase.** The graph is faster, cheaper (fewer tokens), and gives
+you structural context (callers, dependents, test coverage) that file
+scanning cannot.
+
+### When to use graph tools FIRST
+
+- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
+- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
+- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
+- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
+- **Architecture questions**: `get_architecture_overview` + `list_communities`
+
+Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
+
+### Key Tools
+
+| Tool | Use when |
+|------|----------|
+| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
+| `get_review_context` | Need source snippets for review — token-efficient |
+| `get_impact_radius` | Understanding blast radius of a change |
+| `get_affected_flows` | Finding which execution paths are impacted |
+| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
+| `semantic_search_nodes` | Finding functions/classes by name or keyword |
+| `get_architecture_overview` | Understanding high-level codebase structure |
+| `refactor_tool` | Planning renames, finding dead code |
+
+### Workflow
+
+1. The graph auto-updates on file changes (via hooks).
+2. Use `detect_changes` for code review.
+3. Use `get_affected_flows` to understand impact.
+4. Use `query_graph` pattern="tests_for" to check coverage.
@@ -35,3 +35,42 @@ This version has breaking changes — APIs, conventions, and file structure may
 This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

 <!-- END:nextjs-agent-rules -->
+
+<!-- code-review-graph MCP tools -->
+## MCP Tools: code-review-graph
+
+**IMPORTANT: This project has a knowledge graph. ALWAYS use the
+code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
+the codebase.** The graph is faster, cheaper (fewer tokens), and gives
+you structural context (callers, dependents, test coverage) that file
+scanning cannot.
+
+### When to use graph tools FIRST
+
+- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
+- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
+- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
+- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
+- **Architecture questions**: `get_architecture_overview` + `list_communities`
+
+Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
+
+### Key Tools
+
+| Tool | Use when |
+|------|----------|
+| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
+| `get_review_context` | Need source snippets for review — token-efficient |
+| `get_impact_radius` | Understanding blast radius of a change |
+| `get_affected_flows` | Finding which execution paths are impacted |
+| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
+| `semantic_search_nodes` | Finding functions/classes by name or keyword |
+| `get_architecture_overview` | Understanding high-level codebase structure |
+| `refactor_tool` | Planning renames, finding dead code |
+
+### Workflow
+
+1. The graph auto-updates on file changes (via hooks).
+2. Use `detect_changes` for code review.
+3. Use `get_affected_flows` to understand impact.
+4. Use `query_graph` pattern="tests_for" to check coverage.
@@ -0,0 +1,38 @@
+<!-- code-review-graph MCP tools -->
+## MCP Tools: code-review-graph
+
+**IMPORTANT: This project has a knowledge graph. ALWAYS use the
+code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
+the codebase.** The graph is faster, cheaper (fewer tokens), and gives
+you structural context (callers, dependents, test coverage) that file
+scanning cannot.
+
+### When to use graph tools FIRST
+
+- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
+- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
+- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
+- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
+- **Architecture questions**: `get_architecture_overview` + `list_communities`
+
+Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
+
+### Key Tools
+
+| Tool | Use when |
+|------|----------|
+| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
+| `get_review_context` | Need source snippets for review — token-efficient |
+| `get_impact_radius` | Understanding blast radius of a change |
+| `get_affected_flows` | Finding which execution paths are impacted |
+| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
+| `semantic_search_nodes` | Finding functions/classes by name or keyword |
+| `get_architecture_overview` | Understanding high-level codebase structure |
+| `refactor_tool` | Planning renames, finding dead code |
+
+### Workflow
+
+1. The graph auto-updates on file changes (via hooks).
+2. Use `detect_changes` for code review.
+3. Use `get_affected_flows` to understand impact.
+4. Use `query_graph` pattern="tests_for" to check coverage.
@@ -0,0 +1,193 @@
+# Ombrora-YTDLP — Design Spec
+
+Date: 2026-08-10
+
+## Vue d'ensemble
+
+Interface web publique permettant a n'importe quel utilisateur de soumettre une URL de video a telecharger via yt-dlp. Les telechargements sont traites en arriere-plan par un worker Node.js gere par Passenger sur o2switch. Les fichiers sont stockes localement dans un dossier prive et accessibles via un lien temporaire a duree de vie configurable.
+
+---
+
+## Architecture generale
+
+Approche retenue : **Monorepo Next.js + Worker script Node.js separe**.
+
+- `src/` : app Next.js (UI React + API routes)
+- `worker/` : script Node.js long-running qui poll la DB et execute yt-dlp
+- `config/` : configuration centralisee (TTL, concurrence, chemins)
+- `prisma/` : schema et migrations
+- `docker-compose.yml` : MariaDB pour le developpement local
+- Un seul `package.json` a la racine (contrainte o2switch/Passenger)
+
+---
+
+## Structure du projet
+
+```
+Ombrora-YTDLP/
+├── src/
+│   ├── app/
+│   │   ├── page.tsx                  # Formulaire de soumission
+│   │   ├── status/[uuid]/page.tsx    # Page de statut
+│   │   └── api/
+│   │       ├── downloads/route.ts    # POST soumission, GET statut
+│   │       ├── downloads/[uuid]/route.ts
+│   │       └── download/[token]/route.ts  # Stream fichier via token
+│   ├── components/
+│   └── lib/
+│       ├── prisma.ts
+│       ├── rate-limit.ts
+│       └── token.ts
+├── worker/
+│   ├── index.ts          # Worker long-running principal
+│   ├── cron-check.ts     # Verifie que le worker tourne (cron 5 min)
+│   └── cron-cleanup.ts   # Supprime les fichiers expires (cron 1x/jour)
+├── config/
+│   └── app.config.ts
+├── prisma/
+│   └── schema.prisma
+├── docker-compose.yml
+└── package.json
+```
+
+---
+
+## Schema base de donnees (Prisma / MariaDB)
+
+```prisma
+model Download {
+  id          String   @id @default(cuid())
+  uuid        String   @unique @default(uuid())  // expose sur les interfaces
+  url         String
+  status      Status   @default(PENDING)
+  format      String                              // ex: "mp4", "mp3"
+  quality     String                              // ex: "best", "1080p"
+  subtitles   Boolean  @default(false)
+  extraArgs   String?                             // options yt-dlp (JSON array de strings, ex: ["--sponsorblock-remove","all"])
+
+  filePath    String?                             // chemin absolu sur disque
+  fileName    String?                             // nom original
+  fileSize    BigInt?                             // taille en octets
+  errorMsg    String?
+
+  ipAddress   String
+  submittedAt DateTime @default(now())
+  startedAt   DateTime?
+  completedAt DateTime?
+  deletedAt   DateTime?
+
+  tokens      DownloadToken[]
+}
+
+model DownloadToken {
+  id         String   @id @default(cuid())
+  download   Download @relation(fields: [downloadId], references: [id])
+  downloadId String
+  token      String   @unique @default(uuid())
+  expiresAt  DateTime
+  usedAt     DateTime?
+  createdAt  DateTime @default(now())
+}
+
+enum Status {
+  PENDING       // en attente de traitement
+  PROCESSING    // worker en cours
+  DONE          // fichier disponible
+  FAILED        // echec yt-dlp
+  FILE_DELETED  // metadonnees conservees, fichier supprime du disque
+}
+```
+
+**Regles immuables :**
+- Aucune entree n'est jamais supprimee de la DB (historique complet).
+- `id` (cuid) usage interne uniquement ; `uuid` expose sur toutes les interfaces.
+- Le fichier est stocke sous `{STORAGE_PATH}/{uuid}.{extension}`.
+
+---
+
+## Worker (worker/index.ts)
+
+Processus Node.js long-running sous Passenger. Cycle a chaque iteration :
+
+1. Requete DB : `SELECT` les `PENDING` ordonnes par `submittedAt`, limite a `WORKER_CONCURRENCY`.
+2. Passe les entrees selectionnees en `PROCESSING` (atomique : UPDATE WHERE status=PENDING).
+3. Spawne un `worker_thread` par telechargement.
+4. Chaque thread construit la commande yt-dlp :
+   - `--no-playlist` toujours present
+   - `-f {format}` pour le format
+   - `--write-sub --sub-lang fr,en` si `subtitles=true`
+   - `-o {STORAGE_PATH}/{uuid}.%(ext)s` pour le chemin de sortie
+   - extraArgs injectes depuis le champ JSON
+5. Fin du thread :
+   - **Succes** : `status=DONE`, remplit `filePath`, `fileName`, `fileSize`, `completedAt`, cree un `DownloadToken` avec `expiresAt = now + DOWNLOAD_LINK_TTL_HOURS`.
+   - **Echec** : `status=FAILED`, remplit `errorMsg` (stderr yt-dlp).
+6. Attend `WORKER_POLL_INTERVAL_MS` puis recommence.
+
+---
+
+## Crons o2switch (cPanel)
+
+| Script | Frequence | Role |
+|--------|-----------|------|
+| `worker/cron-check.ts` | Toutes les 5 min | Relance le worker s'il n'est pas actif |
+| `worker/cron-cleanup.ts` | 1x par jour | Supprime les fichiers dont `completedAt + TTL < now`, passe `status=FILE_DELETED`, remplit `deletedAt` |
+
+---
+
+## API Routes (Next.js)
+
+| Methode | Route | Description |
+|---------|-------|-------------|
+| `POST` | `/api/downloads` | Valide IP (rate limit), cree l'entree DB, retourne `{ uuid }` |
+| `GET` | `/api/downloads/[uuid]` | Retourne statut et metadonnees du telechargement |
+| `GET` | `/api/download/[token]` | Verifie token (existence, expiration), stream le fichier, marque `usedAt` |
+
+**Rate limiting** (`lib/rate-limit.ts`) :
+- Map en memoire : IP -> `{ count, resetAt }`
+- Limite et fenetre configurables dans `app.config.ts`
+- Pas de Redis requis
+- Hypothese : Passenger tourne avec 1 seul processus Next.js sur o2switch (standard). Si plusieurs processus sont configures, la Map n'est pas partagee et le rate limit serait par-processus — a surveiller.
+
+---
+
+## Configuration (config/app.config.ts)
+
+```typescript
+export const config = {
+  DOWNLOAD_LINK_TTL_HOURS: 24,       // duree de validite du lien temporaire
+  WORKER_CONCURRENCY: 3,             // telechargements en parallele
+  WORKER_POLL_INTERVAL_MS: 10_000,   // intervalle de poll de la DB
+  STORAGE_PATH: '/home/.../storage', // chemin absolu du dossier de stockage
+  RATE_LIMIT_MAX: 5,                 // soumissions max par IP
+  RATE_LIMIT_WINDOW_MS: 3_600_000,   // fenetre de rate limit (1h)
+}
+```
+
+---
+
+## Frontend (React / Next.js)
+
+### `/` — Formulaire de soumission
+- Champ URL
+- Select format (mp4, mp3, webm, ...)
+- Select qualite (best, 1080p, 720p, 480p, ...)
+- Checkbox sous-titres
+- Champ options avancees (optionnel, libre)
+- Soumission -> POST `/api/downloads` -> redirect vers `/status/{uuid}`
+
+### `/status/[uuid]` — Page de statut
+- Polling `GET /api/downloads/[uuid]` toutes les 5 secondes
+- Affichage selon statut :
+  - `PENDING` / `PROCESSING` : indicateur de progression
+  - `DONE` : bouton de telechargement (lien `/api/download/{token}`)
+  - `FAILED` : message d'erreur yt-dlp
+  - `FILE_DELETED` : message "fichier expire, le telechargement n'est plus disponible"
+
+---
+
+## Contraintes de deploiement o2switch
+
+- Un seul `package.json` / `node_modules` a la racine (pas de `frontend/node_modules`).
+- Toute dependance runtime du frontend doit etre dans les `dependencies` de la racine ET dans `frontend/package.json` (si sous-dossier).
+- yt-dlp doit etre installe comme binaire precompile (pas de build depuis les sources).
+- Les dependances avec bindings natifs doivent publier des binaires precompiles pour la plateforme o2switch.
@@ -0,0 +1,7 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
+import "./.next/dev/types/root-params.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
@@ -32,7 +32,6 @@
  "keywords": [],
  "author": "",
  "license": "ISC",
-  "type": "commonjs",
  "dependencies": {
    "@prisma/adapter-mariadb": "^7.9.1",
    "@prisma/client": "^7.9.1",
@@ -11,8 +11,8 @@
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
-    "module": "node16",
-    "moduleResolution": "node16",
+    "module": "esnext",
+    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "react-jsx",
@@ -28,6 +28,12 @@
      }
    ]
  },
+  "ts-node": {
+    "compilerOptions": {
+      "module": "commonjs",
+      "moduleResolution": "node"
+    }
+  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",