airweave / rules

---
globs: **/frontend/**
alwaysApply: false
---
# Airweave Validation System

## Philosophy
Minimal, non-intrusive validation that guides without blocking. No success messages or harsh errors, just essential hints.

## Core Components

### `ValidatedInput` Component
- Replaces standard inputs with validation-aware inputs
- Shows hints after debounce delay (typically 500ms)
- Immediate validation on blur for some fields
- Subtle 30% opacity border colors
- Real-time feedback during typing (not just on submit)

### Validation Rules (`lib/validation/rules.ts`)

#### General Validators
- **`collectionNameValidation`**: 4-64 characters
- **`sourceConnectionNameValidation`**: 4-42 characters
- **`urlValidation`**: Must start with `http://` or `https://`
- **`emailValidation`**: Basic format check
- **`apiKeyValidation`**: Detects placeholder text, shows on change with 500ms debounce

#### Source-Specific Validators

**GitHub**
- **`githubTokenValidation`**: Validates format (ghp_, github_pat_, or 40-char hex)
- **`repoNameValidation`**: Enforces owner/repo format (e.g., "airweave-ai/airweave")

**Stripe**
- **`stripeApiKeyValidation`**: Checks for sk_test_ or sk_live_ prefix, min 20 chars

**Bitbucket**
- **`workspaceValidation`**: Alphanumeric + hyphens + underscores
- **`repoSlugValidation`**: Alphanumeric + hyphens + underscores + dots

**PostgreSQL/Databases**
- **`databaseHostValidation`**: Rejects protocol prefixes (http://, postgresql://, etc.)
- **`databasePortValidation`**: Validates 1-65535 range, rejects non-numeric strings
- **`databaseTablesValidation`**: Accepts "*" or comma-separated table names

**Auth Providers**
- **`clientIdValidation`**: Generic client ID validation
- **`clientSecretValidation`**: Generic client secret validation
- **`authConfigIdValidation`**: For Composio config IDs
- **`accountIdValidation`**: For auth provider account IDs
- **`projectIdValidation`**: For Pipedream project IDs
- **`environmentValidation`**: For environment fields

## Usage

### Basic Usage
```tsx
import { ValidatedInput } from '@/components/ui/validated-input';
import { collectionNameValidation } from '@/lib/validation/rules';

<ValidatedInput
  value={name}
  onChange={setName}
  validation={collectionNameValidation}
  placeholder="Enter name"
  className="..."
/>
```

### Source-Specific Auth Fields
```tsx
import { getAuthFieldValidation } from '@/lib/validation/rules';

// Auto-detects validation based on field name and source
<ValidatedInput
  value={authFields[field.name]}
  onChange={(value) => setAuthFields({ ...authFields, [field.name]: value })}
  validation={getAuthFieldValidation(field.name, sourceDetails?.short_name)}
/>
```

## Field Type Detection

The `getAuthFieldValidation(fieldType: string, sourceShortName?: string)` function auto-detects validation based on field names and optionally source context:

### Source-Specific Routing
- **Stripe `api_key`** → `stripeApiKeyValidation` (when sourceShortName === 'stripe')
- Other sources fall through to generic validators

### Field Name Mapping
- **API Keys & Tokens**
  - `api_key` → Generic API key validation (placeholder detection)
  - `token`, `access_token` → API key validation
  - `personal_access_token` → GitHub token validation

- **URLs**
  - `url`, `endpoint`, `base_url`, `cluster_url`, `uri` → URL validation (requires http:// or https://)

- **Database Fields**
  - `host` → Database host validation (no protocol)
  - `port` → Port range validation (1-65535, numeric only)
  - `tables` → Table list validation (* or comma-separated)

- **User Credentials**
  - `email`, `username` → Email validation
  - `client_id` → Client ID validation
  - `client_secret` → Client secret validation

- **Source-Specific Fields**
  - `repo_name` → GitHub repository validation
  - `workspace` → Bitbucket workspace validation
  - `repo_slug` → Bitbucket repo slug validation (allows dots)

- **Auth Provider Fields**
  - `auth_config_id` → Auth config ID validation
  - `account_id` → Account ID validation
  - `project_id` → Project ID validation
  - `external_user_id` → External user ID validation
  - `environment` → Environment validation

## Validation Timing

### Debounce Settings
- **500ms**: Most text fields (repo names, GitHub tokens, Stripe keys, API keys)
- **300ms**: Database ports
- **0ms**: Some specialized fields requiring immediate feedback

### Show Behavior
- **`showOn: 'change'`**: Validates during typing (after debounce) - used for most fields
- **`showOn: 'blur'`**: Validates only when field loses focus - rarely used

## Visual Feedback
- **Info**: Gray text, amber border at 20% opacity (for empty/incomplete fields)
- **Warning**: Amber text/border at 30% opacity (for invalid inputs)
- **No success states**: We don't celebrate valid input, just guide when invalid

## Implementation Notes

### Port Validation
Uses regex check (`/^\d+$/`) before `parseInt` to reject strings like "123abc" that would otherwise parse as valid.

### Empty Field Handling
Most validators return `{ isValid: true }` for empty fields to allow partial form completion. Backend validation handles required field checks on submission.

### Source Context Awareness
The validation system can route to source-specific validators when `sourceShortName` is provided, enabling different validation logic for fields with common names (like `api_key`) across different sources.