SERVERKIT_DEV_DATABASE_URL points the dev panel at, e.g., a throwaway
sqlite file, so it starts in first-run setup like a fresh install
without touching the usual dev database. The release lab's local
browser journey relies on it.
The venv check probed four imports (dotenv, flask, flask_socketio,
sqlalchemy). Those catch a missing or broken venv, but they are blind to
the common case: a dependency is added to requirements.txt, all four
imports still succeed, dev.sh reports nothing, and the backend dies on
the fifth import at startup. That has derailed several sessions.
Stamp a sha256 of requirements.txt into the venv after a successful
install and compare on each start, so drift triggers a sync. The import
probe stays as the broken-venv check; the hash covers what it cannot see.
Guards: the hash is computed with the venv's own python (no dependency on
sha256sum being installed), an unreadable requirements.txt yields an
empty hash and leaves a working venv alone rather than reinstalling every
start, and the marker is written only after a successful install so a
failed one retries.
Verified by driving the decision logic with pip stubbed: no marker →
install, marker current → skip, requirement appended → install, settled →
skip.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The Windows-side port sweep now respects the same opt-out dev.sh has, and
the startup banner leads with http://localhost:<port> (the WSL interface IP
stays as a printed fallback) so the URL you open is never the dead one.
dev.sh started Vite on 127.0.0.1 — WSL's own loopback, not the one the
browser on Windows talks to. That only ever worked because WSL2 forwards
localhost, and when that forwarding silently stops the app becomes
unreachable while the backend, already bound to 0.0.0.0, keeps answering
on the WSL IP. Half the stack responding and half refusing, with no error
anywhere, is a miserable thing to debug.
Under WSL the frontend now binds all interfaces, so the WSL IP always
works regardless of forwarding, and the banner prints that URL instead of
a localhost one that may not resolve. Both loopback spellings stay in
CORS so localhost keeps working whenever forwarding is up, and non-WSL
setups still bind 127.0.0.1 exactly as before. SERVERKIT_FRONTEND_BIND
overrides the choice.
WSL networking is NAT'd behind the Windows host, so this does not put the
dev server on the LAN.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Add a unified, cross-platform development launcher and update docs/styles to SCSS.
- Add dev/dev.sh: comprehensive Bash dev launcher with stable non-default ports, port resolution/cleanup, WSL-aware behavior, ngrok support, and validation tooling.
- Rewrite Windows entrypoint (dev.ps1) to require WSL and delegate to dev/dev.sh; make top-level dev.sh a thin wrapper that execs dev/dev.sh.
- Add AGENTS.md with project overview, architecture, and development instructions for assistance tools.
- Update docs (CLAUDE.md, CONTRIBUTING.md) to reflect migration from LESS to SCSS and update style guidance.
- Update .gitignore to ignore backend/.venv-wsl, frontend.env.development.local, and /.agents.
- Frontend: add new pages and page-specific SCSS files, update main.scss, components, pages, client/socket services, and vite.config.js to support the SCSS-based frontend changes.
These changes unify local development workflows (especially via WSL), improve port stability, and complete the frontend styling migration from LESS to SCSS.
Juan Denis