feat: scaffold frontend (Vite + React + Vitest)
- Añade scaffold de frontend con Vite y React - Configura Vitest y tests básicos (App, Navbar) - Añade QueryClient y hooks/plantillas iniciales
This commit is contained in:
49
plans/gestor-coleccion-plan-phase-6-complete.md
Normal file
49
plans/gestor-coleccion-plan-phase-6-complete.md
Normal file
@@ -0,0 +1,49 @@
|
||||
## Phase 6 Complete: Frontend base (React + Vite + shadcn/ui)
|
||||
|
||||
Se scaffoldó el frontend mínimo con Vite + React + TypeScript, configuración de Vitest y pruebas básicas. Los tests unitarios escritos pasan correctamente y el proyecto contiene los componentes y rutas base necesarios para continuar con la Fase 7.
|
||||
|
||||
**Files created/changed:**
|
||||
|
||||
- frontend/package.json
|
||||
- frontend/tsconfig.json
|
||||
- frontend/vite.config.ts
|
||||
- frontend/vitest.config.ts
|
||||
- frontend/index.html
|
||||
- frontend/postcss.config.cjs
|
||||
- frontend/tailwind.config.cjs
|
||||
- frontend/src/main.tsx
|
||||
- frontend/src/App.tsx
|
||||
- frontend/src/components/layout/Navbar.tsx
|
||||
- frontend/src/components/layout/Sidebar.tsx
|
||||
- frontend/src/routes/index.tsx
|
||||
- frontend/src/routes/roms.tsx
|
||||
- frontend/src/routes/games.tsx
|
||||
- frontend/src/lib/queryClient.ts
|
||||
- frontend/src/lib/api.ts
|
||||
- frontend/src/hooks/useGames.ts
|
||||
- frontend/src/styles.css
|
||||
- frontend/src/setupTests.ts
|
||||
- frontend/tests/App.spec.tsx
|
||||
- frontend/tests/components/Navbar.spec.tsx
|
||||
|
||||
**Functions created/changed:**
|
||||
|
||||
- `App` component (frontend/src/App.tsx)
|
||||
- `Navbar` component (frontend/src/components/layout/Navbar.tsx)
|
||||
- `Sidebar` placeholder (frontend/src/components/layout/Sidebar.tsx)
|
||||
- `queryClient` export (frontend/src/lib/queryClient.ts)
|
||||
- `useGames` hook (stub) (frontend/src/hooks/useGames.ts)
|
||||
|
||||
**Tests created/changed:**
|
||||
|
||||
- frontend/tests/App.spec.tsx
|
||||
- frontend/tests/components/Navbar.spec.tsx
|
||||
|
||||
**Review Status:** APPROVED
|
||||
|
||||
**Git Commit Message:**
|
||||
feat: scaffold frontend base (Vite + React + Vitest)
|
||||
|
||||
- Añade scaffold de frontend con Vite y React
|
||||
- Configura Vitest y tests básicos (App, Navbar)
|
||||
- Añade QueryClient y hooks/plantillas iniciales
|
||||
@@ -1,28 +0,0 @@
|
||||
## Phase 1 Complete: Contracto de ArchiveReader (list + stream)
|
||||
|
||||
TL;DR: Añadida `streamArchiveEntry` a `archiveReader` y tests unitarios que cubren streaming con `7z`, fallback `unzip -p` y formato no soportado. Los tests unitarios específicos pasan y la implementación es mockeable.
|
||||
|
||||
**Files created/changed:**
|
||||
|
||||
- backend/src/services/archiveReader.ts
|
||||
- backend/tests/services/archiveReader.stream.spec.ts
|
||||
- backend/tests/services/archiveReader.spec.ts
|
||||
|
||||
**Functions created/changed:**
|
||||
|
||||
- `streamArchiveEntry(containerPath, entryPath)` — nueva función que retorna un `Readable` con el contenido de una entrada interna (o `null` para formatos no soportados).
|
||||
- `listArchiveEntries(filePath)` — sin cambios funcionales (pruebas de listado existentes siguen pasando).
|
||||
|
||||
**Tests created/changed:**
|
||||
|
||||
- `backend/tests/services/archiveReader.stream.spec.ts` — tests unitarios para `streamArchiveEntry` (7z success, unzip fallback, unsupported formats).
|
||||
- `backend/tests/services/archiveReader.spec.ts` — tests de listado existentes (sin cambios funcionales relevantes).
|
||||
|
||||
**Review Status:** APPROVED with minor recommendations
|
||||
|
||||
**Git Commit Message:**
|
||||
feat: add streamArchiveEntry to archiveReader and tests
|
||||
|
||||
- Añade `streamArchiveEntry` que devuelve un stream para entradas internas de ZIP/7z
|
||||
- Añade tests unitarios que mockean `child_process.spawn` (7z + unzip fallback)
|
||||
- Mantiene `listArchiveEntries` y documenta dependencia de binarios en CI
|
||||
@@ -1,28 +0,0 @@
|
||||
## Phase 2 Complete: Exponer entradas internas en el escáner
|
||||
|
||||
TL;DR: `scanDirectory` ahora lista entradas internas de contenedores ZIP/7z como items virtuales codificados usando `::`. Se añadieron tests unitarios que mockean `archiveReader.listArchiveEntries` y se introdujo un límite configurable `ARCHIVE_MAX_ENTRIES`.
|
||||
|
||||
**Files created/changed:**
|
||||
|
||||
- backend/src/services/fsScanner.ts
|
||||
- backend/tests/services/fsScanner.archiveEntries.spec.ts
|
||||
|
||||
**Functions created/changed:**
|
||||
|
||||
- `scanDirectory(dirPath)` — ahora, al detectar un archivo contenedor, invoca `listArchiveEntries(container)` y añade items virtuales con:
|
||||
- `path: "${containerPath}::${entryPath}"`
|
||||
- `containerPath`, `entryPath`, `filename`, `size`, `format`, `isArchiveEntry: true`
|
||||
- Añadido `ARCHIVE_MAX_ENTRIES` (configurable via `process.env.ARCHIVE_MAX_ENTRIES`, default 1000).
|
||||
|
||||
**Tests created/changed:**
|
||||
|
||||
- `backend/tests/services/fsScanner.archiveEntries.spec.ts` — valida que `scanDirectory` incluya la entrada interna codificada y que los metadatos (`filename`, `format`, `containerPath`, `entryPath`, `isArchiveEntry`) sean correctos.
|
||||
|
||||
**Review Status:** APPROVED
|
||||
|
||||
**Git Commit Message:**
|
||||
feat: expose archive entries in fsScanner
|
||||
|
||||
- Añade `scanDirectory` support para listar entradas internas de ZIP/7z
|
||||
- Añade test unitario que mockea `archiveReader.listArchiveEntries`
|
||||
- Añade límite configurable `ARCHIVE_MAX_ENTRIES` y comprobación básica de seguridad
|
||||
@@ -1,34 +0,0 @@
|
||||
## Phase 3 Complete: Hashing por stream y soporte en importService
|
||||
|
||||
TL;DR: Implementado `computeHashesFromStream` y adaptado `importDirectory` para procesar entradas internas de archivos usando `archiveReader.streamArchiveEntry`. Añadidos tests unitarios TDD que validan hashing desde streams y el flujo de import para entradas internas.
|
||||
|
||||
**Files created/changed:**
|
||||
|
||||
- backend/src/services/checksumService.ts (añade `computeHashesFromStream`)
|
||||
- backend/src/services/importService.ts (usa `streamArchiveEntry` y `computeHashesFromStream` para `isArchiveEntry`)
|
||||
- backend/tests/services/checksumService.stream.spec.ts (nuevo)
|
||||
- backend/tests/services/importService.archiveEntry.spec.ts (nuevo)
|
||||
|
||||
**Functions created/changed:**
|
||||
|
||||
- `computeHashesFromStream(rs)` — calcula `md5`, `sha1`, `crc32` y `size` desde un `Readable`.
|
||||
- `importDirectory` — para objetos con `isArchiveEntry` obtiene un stream con `streamArchiveEntry(containerPath, entryPath)` y calcula hashes en streaming.
|
||||
|
||||
**Tests creados/ejecutados:**
|
||||
|
||||
- `backend/tests/services/checksumService.stream.spec.ts` — pasa (1 test).
|
||||
- `backend/tests/services/importService.archiveEntry.spec.ts` — pasa (1 test).
|
||||
|
||||
**Review Status:** APPROVED with minor recommendations
|
||||
|
||||
**Notas / Recomendaciones:**
|
||||
|
||||
- Se sugiere limpiar listeners en `computeHashesFromStream` (evitar fugas con streams inusuales).
|
||||
- Algunos specs usan casts `as unknown as vi.Mock`; si TypeScript da errores, convertir esos casts a `import type { Mock } from 'vitest'` y usar `Mock` o usar `any`.
|
||||
|
||||
**Git Commit Message:**
|
||||
feat: stream hashing and archive-entry import support
|
||||
|
||||
- Añade `computeHashesFromStream` para hashing desde streams
|
||||
- Adapta `importDirectory` para procesar entradas internas usando `streamArchiveEntry`
|
||||
- Añade tests unitarios para hashing por stream e import de entradas de archive
|
||||
@@ -1,89 +0,0 @@
|
||||
## Plan: Integrar entradas de archivo en el escáner
|
||||
|
||||
TL;DR: Añadir soporte para listar y procesar entradas dentro de contenedores (ZIP/7z) en el pipeline de importación. Empezamos sin migración de base de datos (usando `::` para codificar `path`), no soportamos archives anidados por ahora, y añadimos límites configurables de tamaño y entradas por archivo. CI instalará `7z` y `unzip` para tests de integración.
|
||||
|
||||
**Phases 4**
|
||||
|
||||
1. **Phase 1: Contracto de ArchiveReader (list + stream)**
|
||||
- **Objective:** Definir y probar la API de `archiveReader` con dos funciones públicas: `listArchiveEntries(containerPath): Promise<Entry[]>` y `streamArchiveEntry(containerPath, entryPath): Readable`.
|
||||
- **Files/Functions to Modify/Create:** `backend/src/services/archiveReader.ts` (añadir `streamArchiveEntry`, documentar comportamiento y fallback a librería JS para ZIP si falta `7z`).
|
||||
- **Tests to Write:**
|
||||
- `backend/tests/services/archiveReader.list.spec.ts` — unit: mockear `child_process.exec` para simular salida de `7z -slt` y `unzip -l`.
|
||||
- `backend/tests/services/archiveReader.stream.spec.ts` — unit: mockear `child_process` y stream; integration opcional (ver Fase 4).
|
||||
- **Steps:**
|
||||
1. Escribir tests (fallando) que describan la API y el formato de `Entry` (`{ name, size }`).
|
||||
2. Implementar `streamArchiveEntry` usando `7z x -so` o `unzip -p` y devolver un `Readable`.
|
||||
3. Añadir fallback para ZIP mediante librería JS si `7z` no está disponible.
|
||||
4. Ejecutar y hacer pasar tests unitarios.
|
||||
- **Acceptance:** Tests unitarios pasan; `streamArchiveEntry` es mockeable y devuelve stream.
|
||||
|
||||
2. **Phase 2: Extender `fsScanner` para exponer entradas (virtual files)**
|
||||
- **Objective:** `scanDirectory(dir)` debe incluir entradas internas de archivos contenedor como items virtuales con `path` codificado (`/abs/archive.zip::inner/path.rom`), `filename` = basename(inner), `isArchiveEntry = true`.
|
||||
- **Files/Functions to Modify/Create:** `backend/src/services/fsScanner.ts` (usar `archiveReader.listArchiveEntries`).
|
||||
- **Tests to Write:**
|
||||
- `backend/tests/services/fsScanner.archiveEntries.spec.ts` — unit: mockear `archiveReader.listArchiveEntries` y verificar formato.
|
||||
- **Steps:**
|
||||
1. Escribir test unitario (fallando) que verifica que `scanDirectory` invoca `archiveReader` y añade entradas codificadas.
|
||||
2. Implementar la integración mínima en `fsScanner` (sin extracción, solo listar entradas).
|
||||
3. Ejecutar tests y ajustar.
|
||||
- **Acceptance:** `scanDirectory` devuelve objetos virtuales estandarizados; tests unitarios pasan.
|
||||
|
||||
3. **Phase 3: Hashing por stream y soporte en `importService` (unit)**
|
||||
- **Objective:** Añadir `computeHashesFromStream(stream)` y hacer que `importDirectory` pueda procesar entradas internas usando `archiveReader.streamArchiveEntry` para obtener hashes sin escribir ficheros temporales.
|
||||
- **Files/Functions to Modify/Create:** `backend/src/services/checksumService.ts` (añadir `computeHashesFromStream`), `backend/src/services/importService.ts` (aceptar `isArchiveEntry` y usar `archiveReader.streamArchiveEntry`).
|
||||
- **Tests to Write:**
|
||||
- `backend/tests/services/checksumService.stream.spec.ts` — unit: hashing desde un `Readable` creado desde un fixture (`backend/tests/fixtures/simple-rom.bin`).
|
||||
- `backend/tests/services/importService.archiveEntry.spec.ts` — unit: mockear `scanDirectory` para devolver entry codificada, mockear `archiveReader.streamArchiveEntry` para devolver stream desde fixture, mockear Prisma y verificar `upsert` con `path` codificado.
|
||||
- **Steps:**
|
||||
1. Escribir tests (fallando) que describan el comportamiento.
|
||||
2. Implementar `computeHashesFromStream(stream)` (MD5/SHA1/CRC32) y refactorizar `computeHashes` para delegar cuando se dispone de stream.
|
||||
3. Hacer `importDirectory` soportar entries internas: obtener stream, calcular hashes, persistir con `path` codificado.
|
||||
4. Ejecutar y pasar tests unitarios.
|
||||
- **Acceptance:** Unit tests pasan; `importDirectory` hace upsert con `path` codificado y hashes correctos.
|
||||
|
||||
4. **Phase 4: Integración real y CI opt-in**
|
||||
- **Objective:** Validar flujo end-to-end con binarios nativos (`7z` y `unzip`) usando fixtures reales en `backend/tests/fixtures/archives/`. CI instalará estos binarios para ejecutar integration tests.
|
||||
- **Files/Functions to Modify/Create:** tests de integración (ej. `backend/tests/services/integration/archive-to-import.spec.ts`), posibles ajustes en `archiveReader` para robustez.
|
||||
- **Tests to Write:**
|
||||
- `backend/tests/services/archiveReader.stream.spec.ts` (integration) — usa `simple.zip` fixture y verifica hashes.
|
||||
- `backend/tests/services/integration/archive-to-import.spec.ts` — E2E: `importDirectory` sobre carpeta con `simple.zip`, verificar DB upsert.
|
||||
- **Steps:**
|
||||
1. Añadir fixtures de archive en `backend/tests/fixtures/archives/` (`simple.zip`, `nested.zip`, `traversal.zip`).
|
||||
2. Marcar tests de integración opt-in mediante `INTEGRATION=1` o detectando binarios con helper (`tests/helpers/requireBinaries.ts`).
|
||||
3. Ejecutar integraciones en local con `INTEGRATION=1` y en CI asegurando que `7z`/`unzip` se instalen.
|
||||
- **Acceptance:** Integration tests pasan en entornos con binarios; fallback JS para ZIP pasa cuando faltan binarios.
|
||||
|
||||
**Decisiones concretas ya tomadas**
|
||||
|
||||
- Representación en DB: usar `path` codificado con `::` (ej. `/abs/archive.zip::dir/inner.rom`) y no tocar Prisma inicialmente.
|
||||
- No soportar archives anidados por ahora (configurable en futuro).
|
||||
- Límites configurables (con valores por defecto razonables):
|
||||
- `ARCHIVE_MAX_ENTRY_SIZE` — tamaño máximo por entrada (por defecto: 200 MB).
|
||||
- `ARCHIVE_MAX_ENTRIES` — máximo de entradas a listar por archive (por defecto: 1000).
|
||||
- CI: instalar `7z` (`p7zip-full`) y `unzip` en runners para ejecutar tests de integración.
|
||||
|
||||
**Riesgos y mitigaciones**
|
||||
|
||||
- Path traversal: sanitizar `entryPath` y rechazar entradas que suban fuera del contenedor.
|
||||
- Zip bombs / entradas gigantes: respetar `ARCHIVE_MAX_ENTRY_SIZE` y abortar hashing si se excede.
|
||||
- Recursos por spawn: imponer timeouts y límites, cerrar streams correctamente.
|
||||
- Archivos cifrados/password: detectar y registrar como `status: 'encrypted'` o saltar.
|
||||
|
||||
**Comandos recomendados para pruebas**
|
||||
|
||||
```bash
|
||||
yarn --cwd backend test
|
||||
yarn --cwd backend test tests/services/archiveReader.list.spec.ts
|
||||
INTEGRATION=1 yarn --cwd backend test tests/services/integration/archive-to-import.spec.ts
|
||||
```
|
||||
|
||||
**Open Questions (resueltas por ti)**
|
||||
|
||||
1. Usar encoding `::` para `path` — Confirmado.
|
||||
2. Soporte de archives anidados — Dejar fuera por ahora.
|
||||
3. Límite por defecto por entrada — Configurable; por defecto 200 MB.
|
||||
4. CI debe instalar `7z` y `unzip` — Confirmado.
|
||||
|
||||
---
|
||||
|
||||
Si apruebas este plan, empezaré la Phase 1: escribiré los tests unitarios para `archiveReader` y delegaré la implementación al subagente implementador siguiendo TDD. ¿Procedo?
|
||||
Reference in New Issue
Block a user