diff --git a/.dockerignore b/.dockerignore index d8a6948c..83304843 100644 --- a/.dockerignore +++ b/.dockerignore @@ -12,8 +12,13 @@ env/ # Build outputs (will be built inside Docker) frontend/dist/ frontend/.vite/ -third-party/avr8js/dist/ -third-party/wokwi-elements/dist/ + +# Reference-only third-party clones — Velxio resolves these from npm at +# build time, so the Docker image doesn't need the upstream sources. +third-party/avr8js/ +third-party/rp2040js/ +third-party/wokwi-elements/ +third-party/wokwi-boards/ # QEMU source & Windows builds (only prebuilt/qemu/ .so files are needed) third-party/qemu-lcgamboa/ diff --git a/.github/workflows/frontend-tests.yml b/.github/workflows/frontend-tests.yml index 54e38282..d1fd4566 100644 --- a/.github/workflows/frontend-tests.yml +++ b/.github/workflows/frontend-tests.yml @@ -13,55 +13,26 @@ jobs: steps: - name: Checkout repository uses: actions/checkout@v4 - # Do NOT use submodules: recursive — the submodule pointers in this repo - # are stale and predate package.json. We clone the libs fresh below. - name: Setup Node.js 22 uses: actions/setup-node@v4 with: node-version: '22' - # Clone third-party fresh (stale submodule pointers can't be used) - - name: Clone third-party - run: | - git clone --depth=1 https://github.com/wokwi/avr8js.git third-party/avr8js - git clone --depth=1 https://github.com/wokwi/rp2040js.git third-party/rp2040js - git clone --depth=1 https://github.com/wokwi/wokwi-elements.git third-party/wokwi-elements + # The metadata generator scans wokwi-elements/src/, which only ships in + # the upstream repo (not on npm). Clone it once for the freshness check. + - name: Clone wokwi-elements (for metadata regeneration only) + run: git clone --depth=1 https://github.com/wokwi/wokwi-elements.git third-party/wokwi-elements - # Cache third-party node_modules to speed up repeated runs - - name: Cache third-party node_modules - uses: actions/cache@v4 - with: - path: | - third-party/avr8js/node_modules - third-party/rp2040js/node_modules - third-party/wokwi-elements/node_modules - key: third-party-${{ hashFiles('third-party/avr8js/package-lock.json', 'third-party/rp2040js/package-lock.json', 'third-party/wokwi-elements/package-lock.json') }} - - # Cache frontend node_modules - name: Cache frontend node_modules uses: actions/cache@v4 with: path: frontend/node_modules key: frontend-${{ hashFiles('frontend/package-lock.json') }} - # Build avr8js (referenced as file: dep in frontend/package.json) - - name: Build avr8js - run: cd third-party/avr8js && npm install && npm run build - - # Build rp2040js (referenced via vite alias to dist/esm) - - name: Build rp2040js - run: cd third-party/rp2040js && npm install && npm run build - - # Build wokwi-elements (referenced as file: dep in frontend/package.json) - - name: Build wokwi-elements - run: cd third-party/wokwi-elements && npm install && npm run build - - # Install frontend deps (picks up file: references to avr8js and wokwi-elements) - name: Install frontend dependencies run: cd frontend && npm ci - # Install root deps (typescript, tsx) so the metadata generator runs - name: Install root dev dependencies run: npm ci @@ -78,6 +49,5 @@ jobs: exit 1 fi - # Run all vitest tests - name: Run tests run: cd frontend && npm test diff --git a/CLAUDE.md b/CLAUDE.md index 01fd6b26..2a58e931 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -72,25 +72,25 @@ npm run lint **Access:** - App: http://localhost:5173 -### Wokwi Libraries (Local Repositories) +### Wokwi Libraries (npm) -The project uses local clones of Wokwi repositories in `third-party/`: -- `wokwi-elements/` - Web Components for electronic parts -- `avr8js/` - AVR8 CPU emulator -- `rp2040js/` - RP2040 emulator +`@wokwi/elements`, `avr8js` and `rp2040js` are pulled directly from the npm +registry — see version pins in `frontend/package.json`. No clone or local +build is required for the Docker image, manual install, or CI. -**Update libraries:** -```bash -update-third-party.bat -``` +The folders under `third-party/` are reference-only (credits / offline +hacking). The one exception is `qemu-lcgamboa` (real source dependency for +ESP32 emulation when rebuilding QEMU). -Or manually: -```bash -cd third-party/wokwi-elements -git pull origin main -npm install -npm run build -``` +**Bump a wokwi lib version:** edit the version string in +`frontend/package.json` and run `npm install` in `frontend/`. + +**Adding new components to wokwi-elements:** the metadata generator +(`scripts/generate-component-metadata.ts`) scans the upstream `src/`, +which the npm package doesn't ship. Clone wokwi-elements once into +`third-party/wokwi-elements/` and run `npm run generate:metadata`. The +script gracefully skips when the clone is absent — `components-metadata.json` +is committed. ### External Dependencies @@ -116,17 +116,11 @@ arduino-cli core install arduino:avr ### Critical Architecture Patterns -**1. Vite Aliases for Local Wokwi Libs** +**1. Wokwi libs come from npm** -The `frontend/vite.config.ts` uses path aliases to import from local repositories: -```typescript -resolve: { - alias: { - 'avr8js': path.resolve(__dirname, '../third-party/avr8js/dist/esm'), - '@wokwi/elements': path.resolve(__dirname, '../third-party/wokwi-elements/dist/esm'), - }, -} -``` +`@wokwi/elements`, `avr8js` and `rp2040js` are listed as regular +dependencies in `frontend/package.json`. Vite resolves them from +`node_modules` like any other package — no aliases, no `file:` references. **2. Multi-File Workspace (useEditorStore)** @@ -404,15 +398,14 @@ There are known pre-existing TS errors that do NOT block the app from running: ### 8. Docker Build — third-party -The git submodule pointers for `rp2040js` and `wokwi-elements` in this repo are stale (point to very old commits that predate `package.json`). The `Dockerfile.standalone` works around this by **cloning the libs fresh from GitHub** at build time instead of COPYing from the build context: +`Dockerfile.standalone` does NOT clone any wokwi-* repos. The frontend stage +just does `COPY frontend/ scripts/` then `npm install && npm run build:docker`, +which pulls `@wokwi/elements`, `avr8js`, `rp2040js` from npm. Board SVGs live +in `frontend/public/boards/`, component SVGs in `frontend/public/component-svgs/`, +and `components-metadata.json` is committed. -```dockerfile -RUN git clone --depth=1 https://github.com/wokwi/avr8js.git third-party/avr8js \ - && git clone --depth=1 https://github.com/wokwi/rp2040js.git third-party/rp2040js \ - && git clone --depth=1 https://github.com/wokwi/wokwi-elements.git third-party/wokwi-elements -``` - -The GitHub Actions workflow does NOT use `submodules: recursive` for this reason. +The frontend-tests CI workflow only clones `wokwi-elements` (for the +metadata staleness check), not the other two. ### 9. Backend Gotchas @@ -445,7 +438,9 @@ npm test ### Adding a New Electronic Component -1. Check if wokwi-elements has the component (see `third-party/wokwi-elements/src/`) +1. Check if wokwi-elements has the component — either browse + https://github.com/wokwi/wokwi-elements or `ls third-party/wokwi-elements/src/` + if the optional clone is present 2. Create React wrapper in `frontend/src/components/components-wokwi/` 3. Add component type to `useSimulatorStore` interface 4. Update SimulatorCanvas to render the component diff --git a/Dockerfile.standalone b/Dockerfile.standalone index e3a75d1c..44ff416f 100644 --- a/Dockerfile.standalone +++ b/Dockerfile.standalone @@ -69,29 +69,10 @@ FROM node:20 AS frontend-builder WORKDIR /app -# Clone third-party fresh from upstream to avoid stale submodule pointers. -# git is pre-installed in the node:20 Debian image. -RUN git clone --depth=1 https://github.com/wokwi/avr8js.git third-party/avr8js \ - && git clone --depth=1 https://github.com/wokwi/rp2040js.git third-party/rp2040js \ - && git clone --depth=1 https://github.com/wokwi/wokwi-elements.git third-party/wokwi-elements \ - && git clone --depth=1 https://github.com/wokwi/wokwi-boards.git third-party/wokwi-boards - -# Build avr8js -WORKDIR /app/third-party/avr8js -RUN npm install && npm run build --if-present - -# Build rp2040js (may have no build script on some commits) -WORKDIR /app/third-party/rp2040js -RUN npm install && npm run build --if-present - -# Build wokwi-elements -WORKDIR /app/third-party/wokwi-elements -RUN npm install && npm run build --if-present - -# Build frontend -# components-metadata.json is already committed; skip generate:metadata -# (it requires wokwi-elements/src which isn't needed at runtime) -WORKDIR /app +# avr8js, rp2040js and @wokwi/elements are pulled directly from the npm +# registry (see frontend/package.json) — no upstream git clones needed. +# Board SVGs live in frontend/public/boards/, component SVGs in +# frontend/public/component-svgs/, and components-metadata.json is committed. COPY frontend/ frontend/ COPY scripts/ scripts/ WORKDIR /app/frontend @@ -144,7 +125,10 @@ COPY backend/app/ ./app/ # run with: docker exec velxio-app python /app/scripts/