webref/scripts/README.md

Scripts Directory

Utility scripts for development, testing, and maintenance.

Available Scripts

🔍 lint.sh

Unified linting for all project code (Python + TypeScript/Svelte).

./scripts/lint.sh

What it checks:

• Backend: Ruff (check + format)
• Frontend: ESLint, Prettier, TypeScript

Auto-enters nix shell if needed

---

🔧 install-hooks.sh

Install git hooks for automatic code quality checks.

./scripts/install-hooks.sh

Installs:

• pre-commit - Runs linting before each commit
• pre-push - Runs tests before push

Skip hooks: git commit --no-verify

---

🧪 test-auth.sh

Automated testing for Phase 3 authentication system.

./scripts/test-auth.sh

Tests:

• Health check
• User registration
• User login
• Protected endpoints
• Token validation
• Password validation
• Error handling

Requires: Backend server running on localhost:8000

---

🚀 quick-start.sh

Automated setup for first-time development.

./scripts/quick-start.sh

Does:

• Creates .env files
• Creates database
• Runs migrations
• Shows next steps

---

Nix Flake Apps

You can also use nix apps for consistent environment:

# Lint all code
nix run .#lint

# Auto-fix linting issues
nix run .#lint-fix

Git Hooks

After running ./scripts/install-hooks.sh:

Pre-commit hook:

• Automatically runs on git commit
• Checks Python (ruff) and TypeScript (ESLint/Prettier)
• Prevents commits with linting errors
• Skip with: git commit --no-verify

Pre-push hook:

• Automatically runs on git push
• Runs full test suite (backend + frontend)
• Prevents pushes with failing tests
• Skip with: git push --no-verify

Development Workflow

Daily Development

# 1. Make changes to code
# 2. Lint runs automatically on commit
git add .
git commit -m "feat: my changes"  # Hooks run automatically

# 3. If lint fails, auto-fix:
nix run .#lint-fix
# Then commit again

Manual Checks

# Before committing, check manually:
./scripts/lint.sh

# Auto-fix issues:
nix run .#lint-fix
# OR
cd backend && ruff format app/
cd frontend && npx prettier --write src/

Troubleshooting

"ruff: command not found"

Solution: Run inside nix shell:

nix develop
./scripts/lint.sh

Or the script will auto-enter nix shell for you.

"node_modules not found"

Solution: Install frontend dependencies:

cd frontend
npm install

Git hooks not running

Solution: Reinstall hooks:

./scripts/install-hooks.sh

Want to disable hooks temporarily

Solution: Use --no-verify:

git commit --no-verify
git push --no-verify

Adding New Linting Rules

Backend (Python)

Edit backend/pyproject.toml:

[tool.ruff.lint]
select = ["E", "F", "I", "W", "N", "UP", "B", "C4", "SIM"]
ignore = ["B008", "N818"]  # Add more as needed

Frontend (TypeScript)

Edit frontend/.eslintrc.cjs and frontend/.prettierrc

CI/CD Integration

The linting checks are also run in CI/CD (see .gitea/workflows/ci.yml).

All code must pass linting before merging to main.