docs: add dev setup guide and make package scripts cross-platform (Windows) (#664)

* chore: update README with environment setup instructions and demo account credentials

fix: replace rm -rf with rimraf in build scripts for cross-platform compatibility

fix: add shell option to pnpm command in db-setup script for Windows compatibility

chore: update package.json files to use rimraf instead of rm -rf for consistency

chore: add rimraf dependency to pnpm-lock.yaml

feat: add postinstall script to install lefthook git hooks in a cross-platform manner

* docs(qa): add QA test plan, flow checklists, and bug-report workflow

Add a repo-native QA execution layer on top of FEATURE_AUDIT.md (the
feature map). Test cases live in the repo; bugs live in GitHub Issues, so
there is no duplicate tracker to keep in sync.

QA system:
- FEATURE_AUDIT.md: the feature map - every feature, its user flow, and
  edge cases with file:line citations.
- qa/README.md: the workflow, severity/difficulty rubrics, label setup,
  and a static feature -> flow coverage map proving all 42 audited
  features have a test plan.
- qa/flows/01..13: per-flow happy-path checklists covering signup &
  onboarding, course authoring, people/invites/roles, student ->
  certificate, AI assistant & tutor, programs/attendance, community,
  org public site, media & import, org settings, public API/MCP,
  enterprise SSO/licensing, and billing & AI credits.
- .github/ISSUE_TEMPLATE/qa-bug.yml: a QA Bug template requiring
  severity, difficulty, area, repro steps, and a screen recording.

Dev tooling:
- package.json: add db:studio and docker:build scripts.
- packages/db: add db:studio (drizzle-kit studio); fix db:reset on
  Windows by spawning the pnpm.cmd shim with shell:true (Node's
  CVE-2024-27980 fix blocks spawning .cmd/.bat without a shell).

* chore: update QA bug template and README for clarity and improved workflow

* docs: enhance DEV_SETUP_NOTES and README for clarity on prerequisites and email setup
chore: update package.json scripts for cross-platform compatibility
feat: add cross-platform Prettier check script for pre-commit hook

* Remove QA documentation and flow files for ClassroomIO

- Deleted the entire QA README.md file which contained the QA process, bug filing guidelines, and feature coverage map.
- Removed all flow files (01 to 13) that detailed the QA testing processes for various features including admin signup, course authoring, people management, student learning, AI assistant, programs, community, org public site, media management, org settings, public API, enterprise SSO, billing, and AI credits.

* fix: update postinstall script

packages/analytics/package.json

@@ -8,7 +8,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "rm -rf dist tsconfig.tsbuildinfo && tsc && tsc-alias",
+    "build": "rimraf dist tsconfig.tsbuildinfo && tsc && tsc-alias",
     "dev": "tsc --watch",
     "format": "prettier --write \"src/**/*.ts\""
   },

packages/db/.env.example

@@ -0,0 +1,3 @@
+# Connection string for the @cio/db scripts (db:setup, db:setup:seed, drizzle-kit).
+# Matches the local Postgres started by docker/docker-compose.yaml.
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/classroomio"

packages/db/README.md

@@ -60,7 +60,11 @@ It performs three steps in order:
 
 **Optional:** Add `--seed` (or `-s`) to run the full seed, including demo users, organizations, courses, and other example data.
 
-Requires `DATABASE_URL` or `PRIVATE_DATABASE_URL` in the environment.
+Requires `DATABASE_URL` or `PRIVATE_DATABASE_URL` in the environment. The scripts load `.env` from this package directory, so bootstrap it once from the template:
+
+```bash
+cp .env.example .env   # then set DATABASE_URL for your DB
+```
 
 ## Seeding
 
@@ -105,13 +109,13 @@ pnpm seed --organizations --organization-members --organization-plan
 
 ### Demo accounts
 
-| Email                            | Password   | Role    | Plan          |
-| -------------------------------- | ---------- | ------- | ------------- |
-| `test@test.com`                  | `password` | Admin   | Basic (free)  |
-| `student@test.com`               | `password` | Student | Basic (free)  |
-| `enterprise@test.com`            | `password` | Admin   | Enterprise    |
-| `enterprise-student@test.com`    | `password` | Student | Enterprise    |
-| `early-adopter@test.com`         | `password` | Admin   | Early Adopter |
-| `early-adopter-student@test.com` | `password` | Student | Early Adopter |
+| Email                            | Password | Role    | Plan          |
+| -------------------------------- | -------- | ------- | ------------- |
+| `admin@test.com`                 | `123456` | Admin   | Basic (free)  |
+| `student@test.com`               | `123456` | Student | Basic (free)  |
+| `enterprise@test.com`            | `123456` | Admin   | Enterprise    |
+| `enterprise-student@test.com`    | `123456` | Student | Enterprise    |
+| `early-adopter@test.com`         | `123456` | Admin   | Early Adopter |
+| `early-adopter-student@test.com` | `123456` | Student | Early Adopter |
 
-Mock user credentials are defined in `users.json`. The encrypted password above corresponds to the literal string `password`.
+Mock user credentials are defined in `users.json`. The demo accounts above use the password `123456`.

packages/db/package.json

@@ -50,9 +50,10 @@
     "dist"
   ],
   "scripts": {
-    "build": "rm -rf dist tsconfig.tsbuildinfo && tsc && tsc-alias",
+    "build": "rimraf dist tsconfig.tsbuildinfo && tsc && tsc-alias",
     "dev": "tsc --watch",
     "db": "drizzle-kit",
+    "db:studio": "drizzle-kit studio",
     "db:reset": "tsx src/scripts/db-reset.ts --skip-seed",
     "db:setup": "tsx src/scripts/db-setup.ts",
     "db:setup:seed": "tsx src/scripts/db-setup.ts --seed",

packages/db/src/scripts/db-reset.ts

@@ -22,7 +22,10 @@ async function runPnpmCommand(commandLabel: string, args: string[]) {
     const child = spawn(pnpmBinary, args, {
       cwd: packageRoot,
       env: process.env,
-      stdio: 'inherit'
+      stdio: 'inherit',
+      // On Windows, spawning the pnpm.cmd shim requires a shell since Node's
+      // CVE-2024-27980 fix (spawning .cmd/.bat without shell throws EINVAL).
+      shell: process.platform === 'win32'
     });
 
     child.on('error', (error) => {

packages/db/src/scripts/db-setup.ts

@@ -22,7 +22,10 @@ async function runPnpmCommand(commandLabel: string, args: string[]) {
     const child = spawn(pnpmBinary, args, {
       cwd: packageRoot,
       env: process.env,
-      stdio: 'inherit'
+      stdio: 'inherit',
+      // On Windows, spawning the pnpm.cmd shim requires a shell since Node's
+      // CVE-2024-27980 fix (spawning .cmd/.bat without shell throws EINVAL).
+      shell: process.platform === 'win32'
     });
 
     child.on('error', (error) => {

packages/jobs/package.json

@@ -38,7 +38,7 @@
     }
   },
   "scripts": {
-    "build": "rm -rf dist tsconfig.tsbuildinfo && tsc && tsc-alias",
+    "build": "rimraf dist tsconfig.tsbuildinfo && tsc && tsc-alias",
     "dev": "tsc --watch",
     "format": "prettier --write ."
   },

packages/mcp/package.json

@@ -14,7 +14,7 @@
     "classroomio-mcp": "./dist/index.js"
   },
   "scripts": {
-    "build": "rm -rf dist tsconfig.tsbuildinfo && node ./scripts/build.mjs",
+    "build": "rimraf dist tsconfig.tsbuildinfo && node ./scripts/build.mjs",
     "typecheck": "tsc --noEmit",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",