From 0c37ef9057020bfacdda9ad500560796132e3df5 Mon Sep 17 00:00:00 2001 From: cproudlock Date: Fri, 17 Jul 2026 15:01:49 -0400 Subject: [PATCH] Dev setup: Windows-first (most devs are on VS Code / Windows) PowerShell commands lead, bash equivalents in comments: venv Activate.ps1 + execution-policy note, copy/$env:, a PowerShell plugin-enable loop, and how the bash naming hook runs under Git Bash (plus the pre-commit hook catching it automatically). The VS Code Check task gets a Windows variant (venv\Scripts, bash for the .sh). Pin shell scripts to LF in .gitattributes so a Windows checkout does not CRLF-corrupt them into 'bad interpreter' failures. --- .gitattributes | 4 +++ .vscode/tasks.json | 3 ++ docs/DEVELOPMENT-SETUP.md | 61 +++++++++++++++++++++++++-------------- 3 files changed, 46 insertions(+), 22 deletions(-) diff --git a/.gitattributes b/.gitattributes index 91bd3db..2be6e2e 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1 +1,5 @@ .env filter=git-crypt diff=git-crypt + +# Shell scripts must stay LF so Git Bash on Windows can run them +*.sh text eol=lf +scripts/check-naming-and-style.sh text eol=lf diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 955e81f..da3f74b 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -36,6 +36,9 @@ "label": "Check: naming + tests + build", "type": "shell", "command": "bash scripts/check-naming-and-style.sh && venv/bin/python -m pytest tests/ -q && cd frontend && npx vitest run && npm run build", + "windows": { + "command": "bash scripts/check-naming-and-style.sh && venv\\Scripts\\python -m pytest tests/ -q && cd frontend && npx vitest run && npm run build" + }, "options": { "cwd": "${workspaceFolder}" }, "problemMatcher": [] } diff --git a/docs/DEVELOPMENT-SETUP.md b/docs/DEVELOPMENT-SETUP.md index ebab2fa..deba90d 100644 --- a/docs/DEVELOPMENT-SETUP.md +++ b/docs/DEVELOPMENT-SETUP.md @@ -6,11 +6,16 @@ material lives elsewhere - naming rules in `CONTRIBUTING.md`, every config variable in the CONFIG guide, plugin authoring in the PLUGIN docs - this is just the on-ramp. -Two ways to run it. **Docker** is the fastest to a working site (one command -brings up MySQL + the app). **Manual (venv + Node)** is what most people -iterate with, because the frontend hot-reloads and the backend restarts on -save. Do Docker first to confirm the box is sane, then switch to manual for -day-to-day work - or go straight to manual if you already have a MySQL. +**Most developers here are on Windows in VS Code** - commands below are +PowerShell first, with the bash equivalent in a comment where they differ. +Install **Git for Windows** (it ships Git Bash, which VS Code and the git +hooks use to run the shell-based naming check) and **VS Code** with the +extensions this repo recommends (you'll be prompted - section 2c). + +Two ways to run it. **Docker** (Docker Desktop on Windows) is the fastest to a +working site. **Manual (venv + Node)** is the daily driver - frontend +hot-reloads, backend restarts on save. Do Docker once to confirm the box is +sane, then use manual for day-to-day work. --- @@ -86,17 +91,19 @@ FLUSH PRIVILEGES; ### Backend -```bash +```powershell python -m venv venv -source venv/bin/activate # Windows: venv\Scripts\activate +venv\Scripts\Activate.ps1 # bash/mac: source venv/bin/activate +# If PowerShell blocks the activate script (execution policy), run once: +# Set-ExecutionPolicy -Scope CurrentUser RemoteSigned pip install -r requirements.txt -cp .env.example .env -# Set SECRET_KEY, JWT_SECRET_KEY, and -# DATABASE_URL=mysql+pymysql://shopdb:devpassword@127.0.0.1:3306/shopdb_flask?charset=utf8mb4 -# CORS_ORIGINS=http://localhost:5173 +copy .env.example .env # bash/mac: cp .env.example .env +# Edit .env - set SECRET_KEY, JWT_SECRET_KEY, and +# DATABASE_URL=mysql+pymysql://shopdb:devpassword@127.0.0.1:3306/shopdb_flask?charset=utf8mb4 +# CORS_ORIGINS=http://localhost:5173 -export FLASK_APP=shopdb +$env:FLASK_APP = "shopdb" # bash/mac: export FLASK_APP=shopdb flask db upgrade # core schema flask plugin upgrade-all # per-plugin schema (ADR-008) flask seed permissions @@ -108,13 +115,18 @@ flask seed admin --username admin --email you@example.com # password printed o Enable the plugins you want visible (they install on a fresh box; some ship disabled). To turn on everything for development: -```bash -for p in computers employees machines measuringtools network notifications \ - printers slides usb warranty knowledgebase geenforce printedparts; do - flask plugin install "$p"; flask plugin enable "$p" -done +PowerShell: + +```powershell +foreach ($p in "computers","employees","machines","measuringtools","network", + "notifications","printers","slides","usb","warranty", + "knowledgebase","geenforce","printedparts") { + flask plugin install $p; flask plugin enable $p +} ``` +(bash/mac: a `for p in ...; do flask plugin install "$p"; ...; done` loop.) + Run the backend ON PORT 5001 - the frontend dev server proxies `/api` and `/static` there (a bare `flask run` uses 5000 and nothing will load): @@ -161,12 +173,17 @@ tasks call `venv/` and `frontend/node_modules`). ## 3. The development loop 1. Make a change. Backend: `flask run` auto-reloads. Frontend: Vite hot-reloads. -2. Before committing, run the same three gates CI runs: - ```bash - bash scripts/check-naming-and-style.sh # the LOCKED naming convention - venv/bin/python -m pytest tests/ -q # backend - cd frontend && npx vitest run && npm run build +2. Before committing, run the same three gates CI runs. In VS Code the + task **Check: naming + tests + build** runs all three; by hand: + ```powershell + bash scripts/check-naming-and-style.sh # naming hook - needs Git Bash + venv\Scripts\python -m pytest tests/ -q # backend + cd frontend; npx vitest run; npm run build ``` + The naming check is a bash script; on Windows it runs under Git Bash + (installed with Git for Windows). The git PRE-COMMIT hook runs it + automatically on every `git commit`, so a bad name is caught even if you + forget to run it - just make sure Git for Windows is installed. 3. Commit in small, working steps. Subject: short, present tense, plain English; body says WHY. Read `CONTRIBUTING.md` before naming anything - the naming hook will reject snake_case DB columns, banned shorthand, and