Skip to content

Commit 0c08883

Browse files
author
Marcos Hernandez
committed
docs: cross-platform Windows 11 / macOS coherente en toda la documentación
Antes habia mismatches entre los docs y la realidad post-portabilidad: - README.md raiz pedia "Node.js 18 LTS" minimo. Real ahora: 22 LTS. - README.md no mencionaba Windows como plataforma soportada. - README.md mostraba flags de compilacion del motor del README original (`-bt=dos -6r -ox -w=3`) que no son los reales del editor (faltaba `-mf -za99 -wcd=...`). - tests/README.md y CLAUDE.md aun referenciaban `run-tests-on-edit.sh` cuando ya esta en `.mjs` desde el commit cross-platform. - tests/README.md decia "Node 20-22 LTS" en troubleshooting, ahora 22-24. Cambios: README.md raiz: - Tabla de requisitos actualizada (Node 22 LTS / 24 soportado, npm 10+). - Nota corta: "Plataformas: editor y suite funcionan identicos en Windows 11 y macOS, verificado en CI matrix." Linkea a tests/README.md para detalle. - Seccion "Compilar el motor DOS" con las dos vias: Watcom nativo en Windows (entorno principal de Javi), DOSBox-X envolviendo Watcom en macOS para verificacion sin Windows. - Flags de compile actualizados a los reales del editor. - Seccion nueva "Tests" con los 3 comandos clave + link a tests/README.md. - Estructura del proyecto extendida con tests/ y goldens/. CLAUDE.md: - Sub-seccion "Cross-platform" anadida en "Workflow TDD" con la matriz CI explicita. - Hook actualizado de .sh a .mjs en la mencion. tests/README.md: - Layout updated: hook .mjs (Node, cross-platform). - Snippet de "probar el hook manualmente" con variantes mac y Windows (PowerShell). - Mencion de troubleshooting actualizada a Node 22-24. - Refs a "run-tests-on-edit.sh" en troubleshooting reemplazadas por .mjs. .instructions.md NO se toca: es del autor original, sin refs Mac-only que requieran fix.
1 parent 385bba7 commit 0c08883

3 files changed

Lines changed: 48 additions & 16 deletions

File tree

‎CLAUDE.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,10 +91,15 @@ wlink system dos4gw file { archivo.obj engine.obj ... } name GAME.exe
9191
## Workflow TDD (obligatorio antes de commitear cambios importantes)
9292

9393
Hay una suite de tests en `tests/` y goldens del codegen en `goldens/`.
94-
El hook `.claude/hooks/run-tests-on-edit.sh` corre los tests del área
94+
El hook `.claude/hooks/run-tests-on-edit.mjs` corre los tests del área
9595
editada en cada `Edit/Write` automáticamente — es la **primera red de
9696
seguridad** mientras editas.
9797

98+
**Cross-platform**: suite y hook funcionan idénticos en **Windows 11** y
99+
**macOS** (CI matrix con `[macos-latest, windows-latest] x Node [22, 24]`).
100+
El hook está escrito en Node, no bash; corre nativo en Windows sin Git Bash
101+
ni WSL. Detalle en [`tests/README.md`](tests/README.md#cross-platform-macos-y-windows).
102+
98103
Como trabajas solo en `main` sin PRs, la segunda red es manual:
99104
ejecutar `npm test` antes de commitear cambios importantes. Esa es la
100105
última oportunidad para mantener `main` verde.

‎README.md‎

Lines changed: 26 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,15 @@ Stack: **Electron + React 18 + Zustand** (editor) · **C + Open Watcom** (motor
99

1010
| Herramienta | Versión mínima | Notas |
1111
|---|---|---|
12-
| Node.js | 18 LTS | |
13-
| npm | 9+ | incluido con Node |
12+
| Node.js | 22 LTS | (24 también soportado) |
13+
| npm | 10+ | incluido con Node |
1414
| [Open Watcom](https://github.com/open-watcom/open-watcom-v2/releases/tag/Current-build) | 2.0 | solo para compilar el motor DOS |
1515
| [DOSBox-X](https://dosbox-x.com/) | cualquier reciente | `mpu401=intelligent` para audio MIDI |
1616

1717
> El editor (Electron) no requiere Watcom. Solo es necesario para generar el `.EXE` del juego.
1818
19+
**Plataformas**: editor y suite de tests funcionan idénticos en **Windows 11** y **macOS** (verificado en CI con matrix `[macos-latest, windows-latest] x Node [22, 24]`). Detalle en [`tests/README.md`](tests/README.md#cross-platform-macos-y-windows).
20+
1921
---
2022

2123
## Instalación
@@ -54,18 +56,22 @@ El instalador queda en `dist/`.
5456

5557
## Compilar el motor DOS
5658

57-
Requiere Open Watcom instalado en `C:\WATCOM\`.
59+
Requiere Open Watcom v2 instalado.
60+
61+
**Windows** (entorno principal): Open Watcom nativo en `C:\WATCOM\`. El panel Build del editor lo invoca directamente.
62+
63+
**macOS**: Open Watcom v2 (la misma versión) ejecutado dentro de DOSBox-X. Produce binarios DOS bit-equivalentes a los de Windows. Útil para verificar y regenerar artefactos sin necesidad de Windows. *(Esta vía se monta como pipeline automatizada en una fase posterior — ver `.claude/plans/`.)*
5864

5965
```bash
60-
# Desde el panel Build del editor (recomendado)
66+
# Desde el panel Build del editor (recomendado, funciona igual en mac y win)
6167
# O manualmente:
6268

63-
wcc386 -bt=dos -6r -ox -w=3 resources/engine/agemki_engine.c
64-
wcc386 -bt=dos -6r -ox -w=3 resources/engine/mididrv.c
65-
wcc386 -bt=dos -6r -ox -w=3 resources/engine/timer.c
69+
wcc386 -bt=dos -3 -mf -ox -za99 -w3 -wcd=202 -wcd=102 -dWALKMAP_CELL_SIZE=8 resources/engine/agemki_engine.c
70+
wcc386 -bt=dos -3 -mf -ox -za99 -w3 -wcd=202 -wcd=102 -dWALKMAP_CELL_SIZE=8 resources/engine/mididrv.c
71+
wcc386 -bt=dos -3 -mf -ox -za99 -w3 -wcd=202 -wcd=102 -dWALKMAP_CELL_SIZE=8 resources/engine/timer.c
6672
# ... resto de módulos
6773

68-
wlink system dos4gw file { agemki_engine.obj mididrv.obj timer.obj ... } name game/GAME.EXE
74+
wlink system dos4g file { agemki_engine.obj mididrv.obj timer.obj ... } name game/GAME.EXE
6975
```
7076
7177
Los logs de compilación se generan en `build/build.log` y `build/watcom.log`.
@@ -99,9 +105,21 @@ agemki/
99105
│ └── renderer/ # UI React (editor visual)
100106
├── resources/
101107
│ └── engine/ # motor C para DOS (wcc386)
108+
├── tests/ # suite de tests (vitest, 219 tests JS, ~7s)
109+
├── goldens/ # outputs binarios esperados del codegen (entran al repo)
102110
└── game/ # salida: GAME.EXE + GAME.DAT (generados, no en git)
103111
```
104112
113+
## Tests
114+
115+
```bash
116+
npm test # corre los 219 tests JS, ~7s
117+
npm run test:watch # vitest en modo watch
118+
npm run goldens:update # regenera goldens tras cambios intencionales
119+
```
120+
121+
Detalle completo (técnica, layout, troubleshooting, cómo añadir tests, workflow TDD para Claude Code) en [`tests/README.md`](tests/README.md).
122+
105123
---
106124
107125

‎tests/README.md‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -211,7 +211,7 @@ agemki/
211211
└── .claude/
212212
├── settings.json permissions + hook PostToolUse
213213
├── hooks/
214-
│ └── run-tests-on-edit.sh hook que dispara tests del área editada
214+
│ └── run-tests-on-edit.mjs hook (Node, cross-platform) que dispara tests del área editada
215215
└── skills/
216216
└── golden-update/
217217
└── SKILL.md flujo seguro para regenerar goldens
@@ -637,26 +637,35 @@ Los goldens del repo no coinciden con tu codegen actual. Posibles causas:
637637

638638
Diagnóstico rápido:
639639
```bash
640-
node --version # debe estar en 20-22 LTS, ver package.json engines
640+
node --version # debe estar en 22 LTS o 24, ver package.json engines
641641
git status
642642
git diff -- src/main/datGenerator.js src/main/sfxGenerator.js src/main/fontGenerator.js
643643
```
644644

645645
### Los tests del hook no se disparan al editar
646646

647-
Verifica que el hook está registrado y es ejecutable:
647+
Verifica que el hook está registrado:
648648
```bash
649-
ls -la .claude/hooks/run-tests-on-edit.sh # debe tener +x
650-
cat .claude/settings.json # debe tener el hook PostToolUse
649+
ls -la .claude/hooks/run-tests-on-edit.mjs # debe existir
650+
cat .claude/settings.json # debe tener el hook PostToolUse
651651
```
652652

653653
Prueba el hook manualmente:
654+
655+
**macOS / Linux**:
654656
```bash
655657
echo '{"tool_name":"Edit","tool_input":{"file_path":"'$(pwd)'/src/renderer/src/store/sceneStore.js"}}' \
656-
| .claude/hooks/run-tests-on-edit.sh
658+
| node .claude/hooks/run-tests-on-edit.mjs
657659
echo "exit: $?"
658660
```
659661

662+
**Windows (PowerShell)**:
663+
```powershell
664+
'{"tool_name":"Edit","tool_input":{"file_path":"' + (Get-Location) + '/src/renderer/src/store/sceneStore.js"}}' `
665+
| node .claude/hooks/run-tests-on-edit.mjs
666+
$LASTEXITCODE
667+
```
668+
660669
### `RangeError: The value of "offset" is out of range` en `serializeScript`
661670

662671
Bug F-04 documentado en [`FINDINGS.md`](FINDINGS.md). Si tu `script.json`
@@ -680,7 +689,7 @@ Es del código de producción, no de los tests. Polish a futuro: añadir
680689
### Los tests del hook tardan demasiado en cada Edit
681690

682691
Si edits triviales disparan toda la suite, revisa el matcher en
683-
`run-tests-on-edit.sh`. El hook está diseñado para correr SOLO los tests
692+
`run-tests-on-edit.mjs`. El hook está diseñado para correr SOLO los tests
684693
del área editada. Si sale > 3s, algo va mal.
685694

686695
---

0 commit comments

Comments
 (0)