@cpretzinger/boss-claude 1.0.0 → 1.0.2

package/lib/validators/README.md

@@ -0,0 +1,497 @@
+# Boss Claude Validators
+
+Validation utilities for Boss Claude integrations and credentials.
+
+## GitHub Token Validator
+
+Validates GitHub personal access tokens to ensure they have the required permissions for Boss Claude operations.
+
+### Required Permissions
+
+- **Issues**: Read/Write access
+- **Contents**: Read/Write access
+
+### Usage
+
+#### Basic Validation
+
+```javascript
+import { validateGitHubToken } from './lib/validators/github.js';
+
+const result = await validateGitHubToken('ghp_your_token_here');
+
+if (result.valid) {
+  console.log(`✅ Token valid for user: ${result.user}`);
+  console.log(`Scopes: ${result.scopes.join(', ')}`);
+} else {
+  console.log(`❌ ${result.error}`);
+  console.log(result.suggestion);
+}
+```
+
+#### Strict Mode
+
+Strict mode requires exact scope matches rather than allowing broader scopes:
+
+```javascript
+const result = await validateGitHubToken('ghp_token', { strict: true });
+```
+
+#### Repository-Specific Testing
+
+Test token permissions against a specific repository:
+
+```javascript
+import { testTokenOnRepository } from './lib/validators/github.js';
+
+const result = await testTokenOnRepository(
+  'ghp_token',
+  'cpretzinger',
+  'boss-claude'
+);
+
+console.log(`Read Issues: ${result.tests.readIssues}`);
+console.log(`Write Issues: ${result.tests.writeIssues}`);
+console.log(`Read Contents: ${result.tests.readContents}`);
+console.log(`Write Contents: ${result.tests.writeContents}`);
+```
+
+#### CLI Validation
+
+Use the test script for quick validation:
+
+```bash
+# Basic validation
+node lib/validators/github.test.js ghp_your_token_here
+
+# Test against specific repository
+node lib/validators/github.test.js ghp_your_token_here cpretzinger boss-claude
+```
+
+### Response Format
+
+#### Success Response
+
+```javascript
+{
+  valid: true,
+  user: 'username',
+  scopes: ['repo', 'workflow'],
+  permissions: {
+    issues: 'read/write',
+    contents: 'read/write'
+  },
+  message: '✅ GitHub token valid for user: username'
+}
+```
+
+#### Error Response
+
+```javascript
+{
+  valid: false,
+  user: 'username',
+  scopes: ['public_repo'],
+  error: 'Token is missing required permissions',
+  missingPermissions: ['issues', 'contents'],
+  currentPermissions: {
+    issues: 'none or read-only',
+    contents: 'read/write'
+  },
+  suggestion: 'To fix this, create a new GitHub token...'
+}
+```
+
+### Supported Token Scopes
+
+The validator recognizes these GitHub token scopes:
+
+| Scope | Description | Provides Issues R/W | Provides Contents R/W |
+|-------|-------------|--------------------|-----------------------|
+| `repo` | Full repository access | ✅ | ✅ |
+| `public_repo` | Public repository access | ✅ | ✅ |
+| `issues` | Issues read/write | ✅ | ❌ |
+| `contents` | Contents read/write | ❌ | ✅ |
+
+### Creating a GitHub Token
+
+#### Classic Personal Access Token
+
+1. Go to [GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)](https://github.com/settings/tokens)
+2. Click "Generate new token (classic)"
+3. Select scopes:
+   - ✅ `repo` (Full control of private repositories) - **Recommended**
+   - OR select individual scopes:
+     - ✅ `public_repo` (Access public repositories)
+     - ✅ `issues` (Read/write issues)
+4. Click "Generate token"
+5. Copy and save the token immediately
+
+#### Fine-Grained Personal Access Token
+
+1. Go to [GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens](https://github.com/settings/personal-access-tokens/new)
+2. Set repository access (all repositories or specific repos)
+3. Set permissions:
+   - **Issues**: Read and write
+   - **Contents**: Read and write
+4. Click "Generate token"
+5. Copy and save the token immediately
+
+### Error Handling
+
+The validator handles these error cases:
+
+- **401 Unauthorized**: Invalid or expired token
+- **403 Forbidden**: Rate limit exceeded or insufficient permissions
+- **Network errors**: Connection issues
+- **Invalid scopes**: Missing required permissions
+
+Each error includes:
+- Clear error message
+- Details about what went wrong
+- Actionable suggestions to fix the issue
+
+### Integration Example
+
+```javascript
+import { validateGitHubToken } from '@cpretzinger/boss-claude/lib/validators/github.js';
+
+async function setupGitHub(token) {
+  const validation = await validateGitHubToken(token);
+
+  if (!validation.valid) {
+    throw new Error(`GitHub setup failed: ${validation.error}\n${validation.suggestion}`);
+  }
+
+  console.log(`✅ GitHub configured for ${validation.user}`);
+  return validation;
+}
+```
+
+### Testing
+
+Run the test suite:
+
+```bash
+# Test with your token
+npm test -- --token=ghp_your_token_here
+
+# Test against specific repository
+npm test -- --token=ghp_token --owner=cpretzinger --repo=boss-claude
+```
+
+### Security Notes
+
+- **Never commit tokens to version control**
+- Use environment variables for token storage
+- Rotate tokens regularly
+- Use fine-grained tokens when possible (more secure)
+- Limit token scope to minimum required permissions
+- Set token expiration dates
+
+### Troubleshooting
+
+#### "Token is missing required permissions"
+
+Your token doesn't have the necessary scopes. Create a new token with:
+- `repo` scope (recommended), OR
+- Both `issues` and `contents` scopes
+
+#### "Invalid or expired GitHub token"
+
+Your token is no longer valid. Generate a new token at GitHub settings.
+
+#### "GitHub API rate limit exceeded"
+
+You've hit the API rate limit. Authenticated requests have a limit of 5,000 requests per hour. Wait for the rate limit to reset or check your usage.
+
+#### "Failed to validate GitHub token"
+
+Network or connection issue. Check:
+- Internet connection
+- GitHub API status: https://www.githubstatus.com/
+- Firewall settings
+
+---
+
+## PostgreSQL Validator
+
+Comprehensive PostgreSQL connection validation with SSL error handling, schema checking, and Railway-specific optimizations.
+
+### Features
+
+- URL format validation
+- Connection testing with automatic retries
+- SSL error handling (graceful fallback)
+- Schema verification (`boss_claude` schema and tables)
+- PostgreSQL version detection
+- Railway database auto-detection and optimization
+- Detailed error reporting with actionable suggestions
+
+### Quick Start
+
+```javascript
+import validator from './lib/validators/postgres.js';
+
+const result = await validator.validate(process.env.BOSS_CLAUDE_PG_URL);
+
+if (result.valid) {
+  console.log('✓ PostgreSQL connection is valid');
+  console.log(`Database: ${result.connection.database}`);
+  console.log(`Version: ${result.connection.versionNumber}`);
+} else {
+  console.error('✗ Validation failed:', result.connection.error);
+}
+```
+
+### Formatted Report
+
+```javascript
+import validator from './lib/validators/postgres.js';
+
+const result = await validator.validate(url);
+validator.printReport(result);
+```
+
+Example output:
+```
+=== PostgreSQL Validation Report ===
+
+URL Validation:
+  ✓ Valid PostgreSQL URL
+  Host: your-postgres-host.example.com:5432
+  Database: railway
+  User: postgres
+  Platform: Railway
+
+Connection Test:
+  ✓ Connected successfully
+  Version: PostgreSQL 17.7
+  Uptime: Wed Jan 21 2026 06:02:51 GMT-0700 (Mountain Standard Time)
+  SSL: Enabled
+
+Schema Check:
+  ✓ Schema boss_claude exists
+  Tables: 4 (achievements, memory_snapshots, sessions, stats_rollups)
+  Functions: 3
+  ✓ All expected tables present
+
+Summary:
+  Overall Status: ✓ VALID
+  Test Duration: 1186ms
+```
+
+### Individual Functions
+
+#### URL Validation
+
+```javascript
+import { validateUrl } from './lib/validators/postgres.js';
+
+const result = validateUrl('postgresql://user:pass@host:5432/db');
+
+if (result.valid) {
+  console.log('Host:', result.components.host);
+  console.log('Port:', result.components.port);
+  console.log('Database:', result.components.database);
+  console.log('Is Railway:', result.components.isRailway);
+}
+```
+
+#### Connection Test
+
+```javascript
+import { testConnection } from './lib/validators/postgres.js';
+
+const result = await testConnection(url, {
+  ssl: true,
+  timeout: 5000,
+  maxRetries: 2
+});
+
+if (result.connected) {
+  console.log('Version:', result.versionNumber);
+  console.log('SSL Enabled:', result.sslEnabled);
+  console.log('Retries:', result.retryCount);
+}
+```
+
+#### Schema Check
+
+```javascript
+import { checkSchema } from './lib/validators/postgres.js';
+
+const result = await checkSchema(url);
+
+if (result.exists) {
+  console.log('Tables:', result.tables);
+  console.log('Missing:', result.missingTables);
+  console.log('Complete:', result.complete);
+}
+```
+
+### Configuration Options
+
+```javascript
+await validator.validate(url, {
+  ssl: true,           // Enable SSL (default: true)
+  timeout: 5000,       // Connection timeout in ms (default: 5000)
+  maxRetries: 2        // Max SSL retry attempts (default: 2)
+});
+```
+
+### Error Handling
+
+The validator handles common PostgreSQL errors gracefully:
+
+**SSL Certificate Errors**
+```javascript
+{
+  connected: false,
+  error: 'SSL connection failed',
+  details: {
+    suggestion: 'Try setting ssl: false or ensure SSL certificates are valid',
+    railwayNote: 'Railway requires rejectUnauthorized: false in SSL config'
+  },
+  retried: true,
+  retryCount: 1
+}
+```
+
+**Authentication Errors**
+```javascript
+{
+  connected: false,
+  error: 'Authentication failed',
+  details: {
+    code: '28P01',
+    suggestion: 'Verify username and password in connection URL'
+  }
+}
+```
+
+**Connection Timeout**
+```javascript
+{
+  connected: false,
+  error: 'Connection timeout',
+  details: {
+    timeout: 5000,
+    suggestion: 'Check network connectivity or increase timeout value'
+  }
+}
+```
+
+**Connection Refused**
+```javascript
+{
+  connected: false,
+  error: 'Connection refused',
+  details: {
+    suggestion: 'Verify host and port are correct and server is running'
+  }
+}
+```
+
+### CLI Testing
+
+```bash
+# Test with environment variable
+export BOSS_CLAUDE_PG_URL="postgresql://user:pass@host:5432/db"
+node test-postgres-validator.js
+
+# Test with explicit URL
+node test-postgres-validator.js "postgresql://user:pass@host:5432/db"
+
+# Run unit tests
+node test-postgres-validator-units.js
+
+# Run error scenario tests
+node test-postgres-validator-scenarios.js
+```
+
+### Railway-Specific Features
+
+The validator automatically detects Railway databases and applies optimal settings:
+
+- Sets `rejectUnauthorized: false` for SSL (required by Railway)
+- Identifies Railway hosts (`railway.app`, `rlwy.net`)
+- Provides Railway-specific error messages
+
+### Schema Requirements
+
+Boss Claude expects these tables in the `boss_claude` schema:
+
+- `sessions` - Boss Claude session tracking
+- `achievements` - User achievement records
+- `memory_snapshots` - State persistence
+
+Missing tables are reported in `missingTables`.
+
+### Integration Example
+
+```javascript
+import validator from './lib/validators/postgres.js';
+
+async function ensureValidConnection() {
+  const url = process.env.BOSS_CLAUDE_PG_URL;
+
+  if (!url) {
+    throw new Error('BOSS_CLAUDE_PG_URL not set');
+  }
+
+  const result = await validator.validate(url, {
+    ssl: true,
+    timeout: 5000,
+    maxRetries: 2
+  });
+
+  if (!result.valid) {
+    console.error('PostgreSQL validation failed');
+    validator.printReport(result);
+    process.exit(1);
+  }
+
+  if (!result.schema.complete) {
+    console.warn('Warning: Missing tables:', result.schema.missingTables);
+  }
+
+  console.log('✓ PostgreSQL connection validated');
+  return result;
+}
+
+// Use in startup
+await ensureValidConnection();
+```
+
+### Troubleshooting
+
+**"SSL connection failed"**
+- Railway databases require `rejectUnauthorized: false`
+- The validator handles this automatically with retry logic
+- If retry fails, check firewall/network settings
+
+**"Authentication failed"**
+- Verify username and password in connection URL
+- Check if database user exists and has proper permissions
+- Ensure password is URL-encoded if it contains special characters
+
+**"Connection timeout"**
+- Increase timeout value: `{ timeout: 10000 }`
+- Check network connectivity
+- Verify database host is accessible
+
+**"Schema boss_claude does not exist"**
+- Run database initialization script
+- Create schema manually: `CREATE SCHEMA boss_claude;`
+- Check if connected to correct database
+
+---
+
+## Future Validators
+
+Additional validators planned for Boss Claude:
+
+- **Redis**: Connection and command permission validation
+- **OpenAI**: API key and quota validation
+- **Email**: SMTP/IMAP credential validation