Summary

This PR implements a complete “run locally” developer flow for the auth service and makes the local migration runner idempotent and resilient.

Key outcomes:

• Adds a migrate:development script that safely runs local D1 migrations and verifies their effects.
• Adds local index application support for D1.
• Updates documentation with an easy quick-path for Windows (PowerShell/WSL) plus the recommended Nix path.
• Makes the migration runner verify skipped migrations actually created their target tables and re-applies any migration that left the DB missing expected schema.

This addresses issue #4290 by providing clear, repeatable steps for running the service locally and a safer migration runner for developer machines.

Changes

migrate-development.js

• New/updated runner:
  • Lists migration files and queries already-applied migrations via wrangler d1 migrations list.
  • Logs [SKIPPED], [APPLYING], [APPLIED] for visibility.
  • Verifies skipped migrations actually created the target tables; re-applies if needed.
  • Runs the indexes applier as a final step in local mode.
  • Ensures wrangler commands are executed from the project root.

apply-indexes.js

• Added --local support to execute index creation against the local D1 preview DB.

package.json

• Added script: "migrate:development": "node ./scripts/migrate-development.js"
• Dev script remains: wrangler dev --port 3333.

README.md / DEVELOP.md (auth.pollinations.ai)

• Added a short, practical “Run locally” quick-path for Windows (PowerShell + WSL) and recommended nix develop instructions.
• Documented .dev.vars usage and the need to provide real secrets (GITHUB_CLIENT_ID/SECRET, JWT_SECRET, etc.).

Verification (what I ran locally)

1. Install dependencies

   npm install
   
   

2. Run idempotent migrations

   npm run migrate:development

   • Listed migrations
   • Skipped already-applied files ([SKIPPED])
   • Verified skipped files created tables; re-applied missing ones
   • Applied local indexes via apply-indexes.js --local

3. Confirm D1 tables exist

   npx wrangler d1 execute github_auth --local --command "SELECT name FROM sqlite_master WHERE type='table';"

   • Verified expected tables exist (users, domains, oauth_state, etc.)

4. Start dev server

   npm run dev

   • Verified worker served at http://127.0.0.1:3333

5. Test /authorize endpoint

   curl -i "http://127.0.0.1:3333/authorize?redirect_uri=http://127.0.0.1:3333/callback"

   • Received HTTP/1.1 302 with correct Location header

6. Verify oauth_state rows

   • Confirmed entries inserted into local D1 DB.

Notes: Missing-table errors observed early were fixed by re-applying migrations; the runner now automatically handles this.

Known manual steps / developer notes

• Secrets: Populate .dev.vars with valid credentials:

  GITHUB_CLIENT_ID=your_real_client_id
  GITHUB_CLIENT_SECRET=your_real_client_secret
  JWT_SECRET=<32+ char secret>
  REDIRECT_URI=http://127.0.0.1:3333/callback
  ADMIN_API_KEY=...

  • GitHub OAuth app callback URL must exactly match REDIRECT_URI.

• Nix: Recommended for repeatable dev; quick PowerShell/WSL path also documented.

• Wrangler / D1: Runner expects a local D1 preview DB (--local). If port conflicts occur, use wrangler dev --no-open --port 3333.

Closes #4290