docs/code-assistant/development-commands.md

Development Commands

Quick reference for common development tasks. Always use uv run python for Python commands and node for Node.js commands.

Development Server

# Start development server (FastAPI backend + JS frontend)
npm run start:dev
# Access at http://localhost:3001

# Development mode with source files (append ?dev to URL)
# http://localhost:3001?dev

# Kill running server and restart
npm run start:dev -- --restart

# Bypass authentication for development/testing
FASTAPI_ALLOW_ANONYMOUS_ACCESS=true npm run start:dev

Options:

• --restart: Kill any existing server process on the port and start fresh

Note: The --restart flag works for both npm run start:dev and npm run start:prod.

Build System

# Full build process
npm run build

# Generate API client from FastAPI OpenAPI spec
npm run generate-client

# Check if API client is outdated
npm run generate-client:check

Testing Commands

# Run tests for changed files (most common)
npm run test:changed

# Unit tests
npm run test:unit:js          # JavaScript unit tests
npm run test:unit:fastapi     # Python unit tests
npm run test:unit             # Both JS and Python units

# API integration tests (local server, fast)
npm run test:api
npm run test:api -- --grep "save"  # Filter by test name

# E2E tests (Playwright)
npm run test:e2e              # Run E2E tests with local server
npm run test:e2e:headed       # Show browser UI
npm run test:e2e:debug        # Step-through debugging
npm run test:e2e:container    # Run in container

# Run all tests
npm run test:all

User Management

# Manage users via CLI
npm run manage user add <username> --password <password> --fullname "<Full Name>" --roles <role1,role2>
npm run manage user list
npm run manage user remove <username>
npm run manage user help

Configuration Management

# Get/set configuration values
npm run manage config get <key>                    # Read from db/config.json
npm run manage config get <key> --default          # Read from config/config.json
npm run manage config set <key> <json_value>       # Set in db/config.json
npm run manage config set <key> <json_value> --default  # Set in both files
npm run manage config delete <key>                 # Delete from db/config.json
npm run manage config delete <key> --default       # Delete from both files

# Value constraints and validation
npm run manage config set <key> --values '["val1", "val2"]'  # Set allowed values
npm run manage config set <key> --type "string"              # Set type constraint

Development Workflow

1. Frontend changes: Edit files in app/src/, test with ?dev URL parameter
2. DO NOT rebuild after frontend changes - The importmap loads source files directly in development mode
3. Backend changes: Server auto-reloads automatically (FastAPI dev server detects changes)
4. Schema updates: Delete schema/cache/ to refresh XSD cache
5. Building is only needed for production and is handled by pre-push git hooks

Critical Reminders

• ALWAYS use uv run python for Python commands
• NEVER restart the dev server manually - It auto-restarts on changes
• Backend changes auto-reload - watch terminal for reload confirmation
• Tests should use containerized server or local test runner, not the dev server
• The ?dev URL parameter enables source file loading for faster frontend iteration

Common NPM Scripts Reference

npm run start:dev              # Start FastAPI development server
npm run start:prod             # Start production server
npm run build                  # Build for production
npm run manage                 # User/config management CLI
npm run test:changed           # Test changed files (smart runner)
npm run test:unit:js           # JavaScript unit tests
npm run test:unit:fastapi      # Python unit tests
npm run test:api               # API integration tests
npm run test:e2e               # E2E tests with Playwright
npm run generate-client        # Generate TypeScript API client