@tyvm/knowhow 0.0.36 → 0.0.37

package/tests/manual/browser-login/README.md

@@ -0,0 +1,189 @@
+# Browser Login Manual Tests
+
+This directory contains comprehensive manual tests for the browser-based login functionality in the Knowhow CLI.
+
+## Test Overview
+
+The browser login implementation includes the following key features:
+- Browser-based authentication as the default login method
+- Cross-platform browser opening (macOS, Windows, Linux)
+- Polling mechanism with exponential backoff
+- JWT token retrieval and secure storage
+- Graceful error handling and user cancellation
+- Backwards compatibility with `--jwt` flag
+
+## Test Files
+
+### 1. `test_browser_login_basic.ts`
+**Purpose**: Tests the core browser login flow end-to-end
+
+**What it tests**:
+- Session creation with the API
+- Browser opening for user authentication
+- Authentication polling and completion
+- JWT retrieval and secure storage
+- File permissions (0o600)
+- JWT format validation
+
+**Prerequisites**:
+- Valid `KNOWHOW_API_URL` environment variable
+- Network connection to Knowhow API
+- Default browser available
+
+**Usage**:
+```bash
+npx tsx ./tests/manual/browser-login/test_browser_login_basic.ts
+```
+
+**Manual steps required**:
+- Complete authentication in the opened browser window
+- Verify browser opened to correct URL
+
+### 2. `test_cli_integration.ts`
+**Purpose**: Tests CLI command integration and backwards compatibility
+
+**What it tests**:
+- `knowhow login` uses browser login by default
+- `knowhow login --jwt` prompts for manual JWT input
+- Command help shows correct options
+- JWT file creation through CLI
+
+**Prerequisites**:
+- Built CLI application (`npm run build`)
+- Valid `KNOWHOW_API_URL` environment variable
+
+**Usage**:
+```bash
+npx tsx ./tests/manual/browser-login/test_cli_integration.ts
+```
+
+**Manual steps required**:
+- Complete browser authentication when prompted
+- Verify help output is correct
+
+### 3. `test_cross_platform_browser.ts`
+**Purpose**: Tests browser opening across different operating systems
+
+**What it tests**:
+- Platform detection (macOS, Windows, Linux)
+- Correct browser command selection (`open`, `start`, `xdg-open`)
+- Browser command availability
+- URL handling with special characters
+- Graceful fallback when browser opening fails
+
+**Prerequisites**:
+- Default browser installed
+- Platform-specific browser commands available
+
+**Usage**:
+```bash
+npx tsx ./tests/manual/browser-login/test_cross_platform_browser.ts
+```
+
+**Manual steps required**:
+- Verify browser opens to test URLs
+- Confirm platform-specific behavior
+
+### 4. `test_error_scenarios.ts`
+**Purpose**: Tests error handling and edge cases
+
+**What it tests**:
+- Invalid API URL handling
+- Missing API URL configuration
+- JWT validation with various inputs
+- File permission handling
+- Error code propagation
+- Graceful cancellation mechanisms
+
+**Prerequisites**:
+- Ability to modify environment variables temporarily
+
+**Usage**:
+```bash
+npx tsx ./tests/manual/browser-login/test_error_scenarios.ts
+```
+
+**Manual steps required**:
+- None (fully automated error scenario testing)
+
+## Running All Tests
+
+To run all tests in sequence:
+
+```bash
+# Run individual tests
+npx tsx ./tests/manual/browser-login/test_error_scenarios.ts
+npx tsx ./tests/manual/browser-login/test_cross_platform_browser.ts
+npx tsx ./tests/manual/browser-login/test_cli_integration.ts
+npx tsx ./tests/manual/browser-login/test_browser_login_basic.ts
+```
+
+## Test Results Interpretation
+
+### ✅ PASSED
+Test completed successfully with expected behavior.
+
+### ⚠️ WARNING  
+Test completed but with minor issues or platform-specific concerns that don't prevent functionality.
+
+### ❌ FAILED
+Test failed due to errors or unexpected behavior that needs to be addressed.
+
+### Manual Verification Required
+Some tests require manual verification (e.g., confirming browser opened correctly) as they test user interaction flows.
+
+## Common Issues and Troubleshooting
+
+### Browser Not Opening
+- **Symptoms**: Browser opening fails or command not found
+- **Solutions**: 
+  - Ensure default browser is installed
+  - Check platform-specific command availability (`open`, `start`, `xdg-open`)
+  - Verify display environment for Linux systems
+
+### Network Errors
+- **Symptoms**: API connection failures or timeouts
+- **Solutions**:
+  - Verify `KNOWHOW_API_URL` is set correctly
+  - Check network connectivity
+  - Confirm API endpoints are accessible
+
+### Permission Errors
+- **Symptoms**: Cannot create or write JWT files
+- **Solutions**:
+  - Check write permissions in project directory
+  - Verify `.knowhow` directory can be created
+  - Check for filesystem restrictions
+
+### Authentication Timeout
+- **Symptoms**: Polling times out before user completes authentication
+- **Solutions**:
+  - Complete authentication more quickly
+  - Check if browser session is blocked by ad blockers
+  - Verify correct authentication URL
+
+## Integration with CI/CD
+
+These manual tests are designed for human verification and are not suitable for automated CI/CD pipelines. For automated testing, consider:
+
+1. Mocking the browser opening functionality
+2. Creating integration tests with test authentication endpoints
+3. Unit testing individual components separately
+
+## Security Considerations
+
+When running these tests:
+- JWT tokens are stored temporarily and cleaned up
+- File permissions are tested to ensure secure storage (0o600)
+- No sensitive data should be logged or persisted beyond test execution
+- Tests clean up after themselves to avoid leaving test artifacts
+
+## Contributing
+
+When adding new tests:
+1. Follow the existing test file naming pattern
+2. Include comprehensive error handling
+3. Provide clear manual steps in comments
+4. Clean up any created files or state
+5. Add appropriate timeout handling
+6. Update this README with new test descriptions

package/tests/manual/browser-login/test_browser_login_basic.ts

@@ -0,0 +1,115 @@
+#!/usr/bin/env npx tsx
+
+/**
+ * Manual Test: Basic Browser Login Flow
+ * 
+ * This test validates the complete browser-based authentication flow:
+ * 1. Creates a login session with the API
+ * 2. Opens browser for user authentication
+ * 3. Polls for authentication completion
+ * 4. Retrieves and stores JWT token
+ * 
+ * Prerequisites:
+ * - Valid KNOWHOW_API_URL environment variable
+ * - Network connection to Knowhow API
+ * - Browser available on the system
+ * 
+ * Usage: npx tsx ./tests/manual/browser-login/test_browser_login_basic.ts
+ */
+
+import { BrowserLoginService } from '../../../src/auth/browserLogin';
+import * as fs from 'fs';
+import * as path from 'path';
+
+async function testBasicBrowserLogin(): Promise<void> {
+  console.log('\n=== Basic Browser Login Test ===\n');
+  
+  let success = false;
+  const configDir = path.join(process.cwd(), '.knowhow');
+  const jwtFile = path.join(configDir, '.jwt');
+  
+  // Clean up any existing JWT file
+  if (fs.existsSync(jwtFile)) {
+    fs.unlinkSync(jwtFile);
+    console.log('🧹 Cleaned up existing JWT file');
+  }
+  
+  try {
+    console.log('1. Initializing BrowserLoginService...');
+    const browserLogin = new BrowserLoginService();
+    
+    console.log('2. Starting browser login flow...');
+    console.log('   Note: This will open your browser and require manual authentication');
+    console.log('   Please complete the authentication process in your browser');
+    
+    await browserLogin.login();
+    
+    console.log('3. Verifying JWT file was created...');
+    if (fs.existsSync(jwtFile)) {
+      const jwtContent = fs.readFileSync(jwtFile, 'utf8');
+      
+      // Check file permissions
+      const stats = fs.statSync(jwtFile);
+      const permissions = stats.mode & parseInt('777', 8);
+      
+      console.log(`   ✅ JWT file created: ${jwtFile}`);
+      console.log(`   ✅ JWT length: ${jwtContent.length} characters`);
+      console.log(`   ✅ File permissions: ${permissions.toString(8)} (should be 600)`);
+      
+      // Basic JWT validation
+      const parts = jwtContent.split('.');
+      if (parts.length === 3) {
+        console.log('   ✅ JWT has correct structure (3 parts)');
+        success = true;
+      } else {
+        console.log('   ❌ JWT has incorrect structure');
+      }
+      
+      if (permissions === parseInt('600', 8)) {
+        console.log('   ✅ JWT file has correct permissions (600)');
+      } else {
+        console.log(`   ⚠️  JWT file permissions may be incorrect: ${permissions.toString(8)}`);
+      }
+      
+    } else {
+      console.log('   ❌ JWT file was not created');
+    }
+    
+  } catch (error) {
+    console.error('❌ Test failed with error:', error.message);
+    
+    if (error.code === 'USER_CANCELLED') {
+      console.log('   ℹ️  Authentication was cancelled by user (this is expected for Ctrl+C)');
+    } else if (error.code === 'TIMEOUT') {
+      console.log('   ⚠️  Authentication timed out (user may not have completed authentication)');
+    } else if (error.code === 'NETWORK_ERROR') {
+      console.log('   ❌ Network error - check API connectivity');
+    }
+  }
+  
+  console.log('\n=== Test Results ===');
+  if (success) {
+    console.log('✅ Browser login test PASSED');
+    console.log('   - Session created successfully');
+    console.log('   - Browser opened for authentication');
+    console.log('   - JWT retrieved and stored securely');
+    process.exit(0);
+  } else {
+    console.log('❌ Browser login test FAILED');
+    console.log('   See error details above');
+    process.exit(1);
+  }
+}
+
+// Handle graceful shutdown
+process.on('SIGINT', () => {
+  console.log('\n\n🛑 Test interrupted by user (Ctrl+C)');
+  console.log('   This tests the graceful cancellation feature');
+  process.exit(0);
+});
+
+// Run the test
+testBasicBrowserLogin().catch((error) => {
+  console.error('Unhandled error:', error);
+  process.exit(1);
+});

package/tests/manual/browser-login/test_cli_integration.ts

@@ -0,0 +1,169 @@
+#!/usr/bin/env npx tsx
+
+/**
+ * Manual Test: CLI Integration Test
+ * 
+ * This test validates the integration of browser login with the CLI command system:
+ * 1. Tests `knowhow login` (browser login as default)
+ * 2. Tests `knowhow login --jwt` (legacy JWT input)
+ * 3. Verifies backwards compatibility
+ * 4. Tests login status verification
+ * 
+ * Prerequisites:
+ * - Built CLI application
+ * - Valid KNOWHOW_API_URL environment variable
+ * - Network connection to Knowhow API
+ * 
+ * Usage: npx tsx ./tests/manual/browser-login/test_cli_integration.ts
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const execAsync = promisify(exec);
+
+async function testCliIntegration(): Promise<void> {
+  console.log('\n=== CLI Integration Test ===\n');
+  
+  const configDir = path.join(process.cwd(), '.knowhow');
+  const jwtFile = path.join(configDir, '.jwt');
+  let testResults: string[] = [];
+  
+  try {
+    // Clean up any existing JWT file
+    if (fs.existsSync(jwtFile)) {
+      fs.unlinkSync(jwtFile);
+      console.log('🧹 Cleaned up existing JWT file\n');
+    }
+    
+    console.log('=== Test 1: Browser Login as Default ===');
+    console.log('Testing: knowhow login (should use browser login)');
+    console.log('Note: This will open your browser - please complete authentication\n');
+    
+    try {
+      // This should use browser login by default
+      const { stdout, stderr } = await execAsync('npm run build && node dist/cli.js login', {
+        timeout: 120000 // 2 minutes timeout
+      });
+      
+      console.log('Command output:', stdout);
+      if (stderr) console.log('Command stderr:', stderr);
+      
+      // Check if JWT file was created
+      if (fs.existsSync(jwtFile)) {
+        const jwtContent = fs.readFileSync(jwtFile, 'utf8');
+        if (jwtContent.split('.').length === 3) {
+          console.log('✅ Test 1 PASSED: Browser login created valid JWT');
+          testResults.push('✅ Browser login as default: PASSED');
+        } else {
+          console.log('❌ Test 1 FAILED: Invalid JWT created');
+          testResults.push('❌ Browser login as default: FAILED (invalid JWT)');
+        }
+      } else {
+        console.log('❌ Test 1 FAILED: No JWT file created');
+        testResults.push('❌ Browser login as default: FAILED (no JWT file)');
+      }
+      
+    } catch (error) {
+      if (error.killed && error.signal === 'SIGTERM') {
+        console.log('⚠️  Test 1 TIMEOUT: User may not have completed authentication');
+        testResults.push('⚠️  Browser login as default: TIMEOUT');
+      } else {
+        console.log('❌ Test 1 ERROR:', error.message);
+        testResults.push('❌ Browser login as default: ERROR');
+      }
+    }
+    
+    // Clean up for next test
+    if (fs.existsSync(jwtFile)) {
+      fs.unlinkSync(jwtFile);
+    }
+    
+    console.log('\n=== Test 2: Legacy JWT Input ===');
+    console.log('Testing: knowhow login --jwt (should prompt for manual JWT input)');
+    
+    // Create a mock interaction that immediately exits
+    try {
+      const { stdout, stderr } = await execAsync('echo "" | npm run build && echo "" | node dist/cli.js login --jwt', {
+        timeout: 10000
+      });
+      
+      console.log('Command output:', stdout);
+      if (stderr) console.log('Command stderr:', stderr);
+      
+      // The command should have prompted for JWT input
+      if (stdout.includes('JWT') || stdout.includes('token') || stderr.includes('JWT') || stderr.includes('token')) {
+        console.log('✅ Test 2 PASSED: --jwt flag triggers manual JWT input');
+        testResults.push('✅ Legacy JWT input: PASSED');
+      } else {
+        console.log('❌ Test 2 FAILED: --jwt flag not working correctly');
+        testResults.push('❌ Legacy JWT input: FAILED');
+      }
+      
+    } catch (error) {
+      // This is expected since we're not providing valid JWT input
+      if (error.message.includes('JWT') || error.message.includes('token')) {
+        console.log('✅ Test 2 PASSED: --jwt flag triggered JWT input prompt');
+        testResults.push('✅ Legacy JWT input: PASSED');
+      } else {
+        console.log('❌ Test 2 FAILED:', error.message);
+        testResults.push('❌ Legacy JWT input: FAILED');
+      }
+    }
+    
+    console.log('\n=== Test 3: Command Help ===');
+    console.log('Testing: knowhow login --help');
+    
+    try {
+      const { stdout, stderr } = await execAsync('npm run build && node dist/cli.js login --help');
+      
+      console.log('Help output:', stdout);
+      
+      if (stdout.includes('--jwt') && stdout.includes('browser')) {
+        console.log('✅ Test 3 PASSED: Help shows both browser and JWT options');
+        testResults.push('✅ Command help: PASSED');
+      } else {
+        console.log('❌ Test 3 FAILED: Help missing expected options');
+        testResults.push('❌ Command help: FAILED');
+      }
+      
+    } catch (error) {
+      console.log('❌ Test 3 ERROR:', error.message);
+      testResults.push('❌ Command help: ERROR');
+    }
+    
+  } catch (error) {
+    console.error('❌ Test suite failed:', error.message);
+  }
+  
+  // Print summary
+  console.log('\n=== Test Summary ===');
+  testResults.forEach(result => console.log(result));
+  
+  const passedTests = testResults.filter(r => r.includes('PASSED')).length;
+  const totalTests = testResults.length;
+  
+  console.log(`\nResults: ${passedTests}/${totalTests} tests passed`);
+  
+  if (passedTests === totalTests) {
+    console.log('🎉 All CLI integration tests PASSED!');
+    process.exit(0);
+  } else {
+    console.log('❌ Some CLI integration tests FAILED');
+    process.exit(1);
+  }
+}
+
+// Handle graceful shutdown
+process.on('SIGINT', () => {
+  console.log('\n\n🛑 Test interrupted by user (Ctrl+C)');
+  process.exit(0);
+});
+
+// Run the test
+testCliIntegration().catch((error) => {
+  console.error('Unhandled error:', error);
+  process.exit(1);
+});

package/tests/manual/browser-login/test_cross_platform_browser.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env npx tsx
+
+/**
+ * Manual Test: Cross-Platform Browser Opening
+ * 
+ * This test validates that the browser opening functionality works across different platforms:
+ * 1. Detects the current platform
+ * 2. Tests browser opening with a test URL
+ * 3. Validates the correct command is used for each platform
+ * 4. Tests fallback behavior when browser opening fails
+ * 
+ * Prerequisites:
+ * - Default browser installed on the system
+ * - Network connection (for test URL)
+ * 
+ * Usage: npx tsx ./tests/manual/browser-login/test_cross_platform_browser.ts
+ */
+
+import { openBrowser } from '../../../src/auth/browserLogin';
+import * as os from 'os';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+async function testCrossPlatformBrowser(): Promise<void> {
+  console.log('\n=== Cross-Platform Browser Opening Test ===\n');
+  
+  const platform = os.platform();
+  console.log(`Detected platform: ${platform}`);
+  
+  let testResults: string[] = [];
+  
+  // Test 1: Platform Detection
+  console.log('\n=== Test 1: Platform Detection ===');
+  
+  let expectedCommand: string;
+  switch (platform) {
+    case 'darwin':
+      expectedCommand = 'open';
+      console.log('✅ Platform: macOS - should use "open" command');
+      break;
+    case 'win32':
+      expectedCommand = 'start';
+      console.log('✅ Platform: Windows - should use "start" command');
+      break;
+    default:
+      expectedCommand = 'xdg-open';
+      console.log('✅ Platform: Linux/Unix - should use "xdg-open" command');
+      break;
+  }
+  testResults.push('✅ Platform detection: PASSED');
+  
+  // Test 2: Command Availability
+  console.log('\n=== Test 2: Browser Command Availability ===');
+  
+  try {
+    // Test if the expected command exists
+    await execAsync(`which ${expectedCommand} || where ${expectedCommand}`);
+    console.log(`✅ Browser command "${expectedCommand}" is available`);
+    testResults.push('✅ Browser command availability: PASSED');
+  } catch (error) {
+    console.log(`⚠️  Browser command "${expectedCommand}" may not be available`);
+    console.log('   This could cause browser opening to fail gracefully');
+    testResults.push('⚠️  Browser command availability: WARNING');
+  }
+  
+  // Test 3: Browser Opening with Test URL
+  console.log('\n=== Test 3: Browser Opening Test ===');
+  console.log('Testing browser opening with a test URL...');
+  console.log('Note: This should open https://example.com in your default browser');
+  
+  const testUrl = 'https://example.com';
+  
+  try {
+    await openBrowser(testUrl);
+    console.log('✅ Browser opening completed without errors');
+    
+    // Give user time to confirm
+    console.log('\nDid your browser open to https://example.com? (This test requires manual verification)');
+    console.log('The test will continue in 10 seconds...');
+    
+    await new Promise(resolve => setTimeout(resolve, 10000));
+    
+    testResults.push('✅ Browser opening: PASSED (manual verification required)');
+    
+  } catch (error) {
+    console.log(`⚠️  Browser opening failed gracefully: ${error.message}`);
+    console.log('   This is expected behavior - the application should continue working');
+    testResults.push('✅ Browser opening fallback: PASSED');
+  }
+  
+  // Test 4: Invalid URL Handling
+  console.log('\n=== Test 4: Invalid URL Handling ===');
+  
+  try {
+    await openBrowser('not-a-valid-url');
+    console.log('✅ Invalid URL handled gracefully');
+    testResults.push('✅ Invalid URL handling: PASSED');
+  } catch (error) {
+    console.log(`⚠️  Invalid URL caused error: ${error.message}`);
+    console.log('   This is acceptable as long as it doesn\'t crash the application');
+    testResults.push('✅ Invalid URL handling: PASSED (graceful failure)');
+  }
+  
+  // Test 5: URL with Special Characters
+  console.log('\n=== Test 5: Special Characters in URL ===');
+  
+  const specialUrl = 'https://example.com/path?param=value&other=test#fragment';
+  
+  try {
+    await openBrowser(specialUrl);
+    console.log('✅ URL with special characters handled correctly');
+    testResults.push('✅ Special characters handling: PASSED');
+  } catch (error) {
+    console.log(`⚠️  Special characters in URL caused issues: ${error.message}`);
+    testResults.push('⚠️  Special characters handling: WARNING');
+  }
+  
+  // Platform-specific tests
+  console.log('\n=== Test 6: Platform-Specific Command Testing ===');
+  
+  try {
+    const testCommand = getTestCommand(platform);
+    if (testCommand) {
+      console.log(`Testing platform-specific command: ${testCommand}`);
+      await execAsync(testCommand);
+      console.log('✅ Platform-specific command executed successfully');
+      testResults.push('✅ Platform-specific command: PASSED');
+    } else {
+      console.log('⚠️  No platform-specific test available');
+      testResults.push('⚠️  Platform-specific command: SKIPPED');
+    }
+  } catch (error) {
+    console.log(`❌ Platform-specific command failed: ${error.message}`);
+    testResults.push('❌ Platform-specific command: FAILED');
+  }
+  
+  // Print summary
+  console.log('\n=== Test Summary ===');
+  testResults.forEach(result => console.log(result));
+  
+  const passedTests = testResults.filter(r => r.includes('PASSED')).length;
+  const warningTests = testResults.filter(r => r.includes('WARNING')).length;
+  const failedTests = testResults.filter(r => r.includes('FAILED')).length;
+  const totalTests = testResults.length;
+  
+  console.log(`\nResults: ${passedTests}/${totalTests} passed, ${warningTests} warnings, ${failedTests} failed`);
+  
+  if (failedTests === 0) {
+    console.log('🎉 Cross-platform browser tests completed successfully!');
+    if (warningTests > 0) {
+      console.log('   Some warnings detected - check platform-specific behavior');
+    }
+    process.exit(0);
+  } else {
+    console.log('❌ Some cross-platform browser tests failed');
+    process.exit(1);
+  }
+}
+
+function getTestCommand(platform: string): string | null {
+  switch (platform) {
+    case 'darwin':
+      // Test opening a simple file/app that should exist
+      return 'open -a "System Preferences" || echo "Could not open System Preferences"';
+    case 'win32':
+      // Test opening notepad which should be available on all Windows systems
+      return 'start notepad && timeout 2 && taskkill /f /im notepad.exe 2>nul || echo "Notepad test completed"';
+    default:
+      // Test xdg-open with a simple command
+      return 'xdg-open --version || echo "xdg-open version check completed"';
+  }
+}
+
+// Handle graceful shutdown
+process.on('SIGINT', () => {
+  console.log('\n\n🛑 Test interrupted by user (Ctrl+C)');
+  process.exit(0);
+});
+
+// Run the test
+testCrossPlatformBrowser().catch((error) => {
+  console.error('Unhandled error:', error);
+  process.exit(1);
+});