docs: add CLAUDE.md and TROUBLESHOOTING.md, fix npm install for Node.js v24

- Add CLAUDE.md with architecture overview and development guidance for Claude Code - Add TROUBLESHOOTING.md with solutions for common development issues - Fix npm install failures in WSL with Node.js v24 by using --openssl-legacy-provider - Document Node.js v24 + OpenSSL 3.x WSL incompatibility and workarounds The CLAUDE.md file provides future Claude Code instances with essential information about: - Commands for testing and development - Core architecture (engine.js, generator.js, template-v2 system) - Key concepts (field mapping, placeholder mapping, layout constants) - Common development tasks and patterns The TROUBLESHOOTING.md file provides detailed solutions for: - npm install SSL cipher errors in WSL environments - CORS errors when loading timeline - Template validation issues - CSV data loading problems - Test failures Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-23 15:22:21 +01:00
parent d5c1ca239d
commit 4e92665358
3 changed files with 596 additions and 1 deletions
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,376 @@
+# Troubleshooting Guide
+
+This document provides solutions to common issues encountered when developing with TimelineSvg.
+
+## Quick Reference
+
+| Problem | Quick Fix | See Section |
+|---------|-----------|-------------|
+| `npm install` fails with SSL cipher errors in WSL | `export NODE_OPTIONS="--openssl-legacy-provider" && npm install` | [npm Install Failures](#npm-install-failures-in-wsl-with-nodejs-v24) |
+| CORS errors when opening index.html | `make serve` or `python3 -m http.server 8000` | [CORS Errors](#cors-errors-when-loading-timeline) |
+| "Template is missing required elements" | Check `<defs>` section has all 3 template IDs | [Template Validation](#template-validation-errors) |
+| CSV loads but shows 0 valid items | Verify `fieldMapping` matches CSV column names | [CSV Data Not Loading](#csv-data-not-loading) |
+| Tests failing or timing out | `make clean && make install` | [Tests Failing](#tests-failing) |
+
+---
+
+## npm Install Failures in WSL with Node.js v24
+
+### Problem Description
+
+**Symptoms:**
+- `npm install` fails with error: `ERR_SSL_CIPHER_OPERATION_FAILED`
+- Error message contains: `Provider routines:ossl_gcm_stream_update:cipher operation failed`
+- May also see `ETXTBSY` (text file busy) errors during esbuild installation
+- Occurs specifically in WSL (Windows Subsystem for Linux) environments
+- Appears with Node.js v24.x
+
+**Error Example:**
+```
+npm error code ERR_SSL_CIPHER_OPERATION_FAILED
+npm error C09CD49A5C750000:error:1C800066:Provider routines:ossl_gcm_stream_update:cipher operation failed:../deps/openssl/openssl/providers/implementations/ciphers/ciphercommon_gcm.c:346:
+```
+
+### Root Cause
+
+Node.js v24 upgraded to OpenSSL 3.x, which introduced stricter cipher requirements and different default providers. When running in WSL, there's a compatibility issue between:
+- Node.js v24's OpenSSL 3.x implementation
+- WSL's kernel/filesystem handling of cryptographic operations
+- npm's package extraction process (which uses encryption for tar.gz files)
+
+The cipher operation fails during package decompression, preventing successful installation.
+
+### Solution
+
+**Quick Fix (Recommended):**
+
+Use the provided Makefile, which includes the workaround:
+```bash
+make install
+```
+
+**Manual Fix:**
+
+If not using the Makefile, set the `NODE_OPTIONS` environment variable before running npm:
+```bash
+export NODE_OPTIONS="--openssl-legacy-provider"
+npm install
+```
+
+**Permanent Fix (for your shell session):**
+
+Add to your `~/.bashrc` or `~/.zshrc`:
+```bash
+export NODE_OPTIONS="--openssl-legacy-provider"
+```
+
+Then reload your shell:
+```bash
+source ~/.bashrc
+```
+
+### Step-by-Step Recovery
+
+If you're in a broken state with partial installation:
+
+1. **Clean everything:**
+   ```bash
+   rm -rf node_modules package-lock.json
+   npm cache clean --force
+   ```
+
+2. **Install with workaround:**
+   ```bash
+   export NODE_OPTIONS="--openssl-legacy-provider"
+   npm install
+   ```
+
+3. **Verify installation:**
+   ```bash
+   npm test
+   ```
+
+   Should show: `58 passed (58)` across 3 test files
+
+### Alternative Solutions
+
+**Option A: Use Node.js v22 (LTS)**
+
+If you don't need Node.js v24 features:
+```bash
+# Using nvm (Node Version Manager)
+nvm install 22
+nvm use 22
+npm install
+```
+
+Node.js v22 uses OpenSSL 1.1.1 and doesn't have this issue.
+
+**Option B: Use npm's legacy peer deps flag**
+
+Sometimes combining flags helps:
+```bash
+export NODE_OPTIONS="--openssl-legacy-provider"
+npm install --legacy-peer-deps
+```
+
+### Prevention
+
+**For New Projects:**
+
+Update your project's documentation and Makefile to include the workaround automatically. See the current `Makefile` for reference.
+
+**For CI/CD:**
+
+Add to your CI configuration:
+```yaml
+# GitHub Actions example
+env:
+  NODE_OPTIONS: "--openssl-legacy-provider"
+
+# GitLab CI example
+variables:
+  NODE_OPTIONS: "--openssl-legacy-provider"
+```
+
+### Verification
+
+After applying the fix, verify with:
+
+```bash
+# Check Node.js version
+node --version  # Should show v24.x.x
+
+# Check installation succeeded
+ls -la node_modules | head -5
+
+# Run tests to confirm everything works
+npm test
+
+# Expected output:
+# ✓ Test Files  3 passed (3)
+# ✓ Tests  58 passed (58)
+```
+
+### Related Issues
+
+- **esbuild ETXTBSY errors**: Often occur together with SSL cipher errors. The same solution fixes both.
+- **Vitest installation failures**: Vitest depends on esbuild, so the fix resolves Vitest installation issues too.
+
+### When This Won't Help
+
+This solution specifically addresses Node.js v24 + OpenSSL 3.x + WSL issues. It won't help with:
+- Network connectivity problems (check `npm config get registry`)
+- Permissions issues (avoid `sudo npm install`, use `nvm` instead)
+- Disk space problems (check with `df -h`)
+- Corrupted npm cache (run `npm cache verify`)
+
+---
+
+## CORS Errors When Loading Timeline
+
+### Problem Description
+
+**Symptoms:**
+- Opening `index.html` directly in browser (file:// protocol)
+- Console shows CORS errors when trying to load CSV, CSS, or SVG files
+- Timeline doesn't render, shows "Keine Timeline verfügbar"
+
+### Solution
+
+Serve the application via HTTP:
+
+```bash
+# Using the Makefile (recommended)
+make serve
+
+# Or manually with Python 3
+python3 -m http.server 8000
+
+# Or with Python 2
+python -m SimpleHTTPServer 8000
+
+# Or with Node.js/npx
+npx serve -l 8000
+```
+
+Then open: `http://localhost:8000`
+
+### Why This Happens
+
+Browsers enforce CORS (Cross-Origin Resource Sharing) restrictions on `file://` URLs for security. Loading external resources (CSV, CSS, SVG) requires HTTP protocol.
+
+---
+
+## Template Validation Errors
+
+### Problem Description
+
+**Symptoms:**
+- Error: "Template is missing required elements: month-template"
+- Error: "Failed to extract template element"
+- Template renders but with empty placeholders
+
+### Solution
+
+**Check template structure:**
+
+1. Open your `template-v2.svg` in a text editor
+2. Verify it has a `<defs>` section
+3. Ensure all three required template elements exist:
+   ```svg
+   <defs>
+     <g id="month-template" style="display:none">...</g>
+     <g id="lane-template" style="display:none">...</g>
+     <g id="item-template" style="display:none">...</g>
+   </defs>
+   ```
+
+4. Check that IDs are exactly as shown (case-sensitive)
+5. Verify templates contain proper placeholders (e.g., `{{MONTH_X}}`, `{{LANE_NAME}}`)
+
+**Common mistakes:**
+- Template elements outside `<defs>` section
+- Incorrect `id` attributes (e.g., `month_template` instead of `month-template`)
+- Missing `style="display:none"` (causes templates to show in output)
+- Malformed XML/SVG (unclosed tags)
+
+**Quick fix:**
+
+Copy a working template from `example/template-v2.svg` and modify it.
+
+See `TEMPLATE_V2_GUIDE.md` for comprehensive template documentation.
+
+---
+
+## CSV Data Not Loading
+
+### Problem Description
+
+**Symptoms:**
+- CSV file loads but no items appear
+- Debug panel shows "Valid Items: 0"
+- Console shows "Keine gültigen Items gefunden"
+
+### Solution
+
+**Check field mappings:**
+
+1. Open debug panel in the UI (should show automatically)
+2. Compare "CSV Structure Preview" headers with "Field Mapping"
+3. Ensure `project.json` field mappings match your CSV column names exactly
+
+**Example:**
+
+If your CSV has:
+```csv
+Task_ID,Task_Name,Due_Date,Epic
+```
+
+Your `project.json` must have:
+```json
+{
+  "fieldMapping": {
+    "id": "Task_ID",
+    "title": "Task_Name",
+    "lane": "Epic",
+    "due": ["Due_Date"]
+  }
+}
+```
+
+**Check date formats:**
+
+Supported formats:
+- `YYYY-MM-DD` (e.g., `2025-12-31`)
+- `YYYY/MM/DD` (e.g., `2025/12/31`)
+- `DD.MM.YYYY` (e.g., `31.12.2025`)
+
+Unsupported formats will cause items to be filtered out.
+
+### Verification
+
+Look at the debug panel:
+- "Parsed Rows" should match your CSV row count
+- "Valid Items" should equal "Parsed Rows" (or close to it)
+- If they differ significantly, check date formats and required fields
+
+---
+
+## Tests Failing
+
+### Problem Description
+
+**Symptoms:**
+- `npm test` fails with errors
+- Tests timeout or hang
+- jsdom errors
+
+### Solution
+
+**Basic troubleshooting:**
+
+1. **Reinstall dependencies:**
+   ```bash
+   make clean
+   make install
+   ```
+
+2. **Check Node.js version:**
+   ```bash
+   node --version  # Should be v22+ or v24+
+   ```
+
+3. **Run specific test file:**
+   ```bash
+   npm test test/generator.test.js
+   ```
+
+4. **Check test environment:**
+   ```bash
+   cat vitest.config.js
+   ```
+   Should show `environment: 'jsdom'`
+
+5. **Clear Vitest cache:**
+   ```bash
+   rm -rf .vitest node_modules/.vitest
+   npm test
+   ```
+
+### Expected Test Results
+
+All tests passing:
+```
+✓ test/generator.test.js (36 tests)
+✓ test/engine.test.js (7 tests)
+✓ test/integration.test.js (15 tests)
+
+Test Files  3 passed (3)
+Tests  58 passed (58)
+```
+
+---
+
+## Need More Help?
+
+1. Check existing documentation:
+   - `README.md` - Overview and features
+   - `TEMPLATE_V2_GUIDE.md` - Template creation and customization
+   - `CLAUDE.md` - Architecture and development guide
+
+2. Enable debug mode:
+   - Debug panel shows automatically when loading projects
+   - Check browser console for detailed error messages
+
+3. Verify file paths:
+   - All paths in `project.json` are relative to the project folder
+   - Use forward slashes (`/`) not backslashes (`\`)
+
+4. Test with example project:
+   ```bash
+   # Open browser to http://localhost:8000
+   # Example project should auto-load successfully
+   ```
+
+   If example works but your project doesn't, compare configurations.