@friggframework/devtools 2.0.0-next.7 → 2.0.0-next.71

package/frigg-cli/__tests__/utils/test-setup.js

@@ -0,0 +1,287 @@
+/**
+ * Global test setup for Frigg CLI tests
+ * This file is executed before each test file
+ */
+
+// Store original environment
+const originalEnv = process.env;
+const originalConsole = { ...console };
+// Store original process methods (not entire object due to read-only properties)
+const originalProcessExit = process.exit;
+const originalProcessCwd = process.cwd;
+
+// Mock console to prevent noisy output during tests
+global.console = {
+  ...console,
+  log: jest.fn(),
+  info: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+  debug: jest.fn()
+};
+
+// Set up test environment variables
+process.env = {
+  ...originalEnv,
+  NODE_ENV: 'test',
+  HOME: '/mock/home',
+  PATH: '/mock/path',
+  CI: 'true'
+};
+
+// Global setup before each test
+beforeEach(() => {
+  // Clear all mocks
+  jest.clearAllMocks();
+  
+  // Reset timers
+  jest.clearAllTimers();
+  
+  // Reset modules
+  jest.resetModules();
+
+  // Mock process.exit to prevent actual exit
+  process.exit = jest.fn();
+
+  // Mock process.cwd to return predictable path
+  process.cwd = jest.fn().mockReturnValue('/mock/cwd');
+  
+  // Reset console mocks
+  global.console.log.mockClear();
+  global.console.info.mockClear();
+  global.console.warn.mockClear();
+  global.console.error.mockClear();
+  global.console.debug.mockClear();
+});
+
+// Global cleanup after each test
+afterEach(() => {
+  // Restore environment
+  process.env = { ...originalEnv };
+
+  // Restore process methods
+  process.exit = originalProcessExit;
+  process.cwd = originalProcessCwd;
+
+  // Clear any remaining timers
+  jest.clearAllTimers();
+
+  // Unmock all modules
+  jest.restoreAllMocks();
+});
+
+// Global teardown after all tests
+afterAll(() => {
+  // Restore original environment completely
+  process.env = originalEnv;
+
+  // Restore original console
+  global.console = originalConsole;
+
+  // Restore original process methods
+  process.exit = originalProcessExit;
+  process.cwd = originalProcessCwd;
+});
+
+// Custom matchers for CLI testing
+expect.extend({
+  toBeValidExitCode(received) {
+    const validCodes = [0, 1, 2];
+    const pass = validCodes.includes(received);
+    
+    if (pass) {
+      return {
+        message: () => `expected ${received} not to be a valid exit code`,
+        pass: true
+      };
+    } else {
+      return {
+        message: () => `expected ${received} to be a valid exit code (0, 1, or 2)`,
+        pass: false
+      };
+    }
+  },
+  
+  toHaveLoggedError(received, expected) {
+    const errorLogs = global.console.error.mock.calls;
+    const pass = errorLogs.some(call => 
+      call.some(arg => 
+        typeof arg === 'string' && arg.includes(expected)
+      )
+    );
+    
+    if (pass) {
+      return {
+        message: () => `expected not to have logged error containing "${expected}"`,
+        pass: true
+      };
+    } else {
+      return {
+        message: () => `expected to have logged error containing "${expected}"`,
+        pass: false
+      };
+    }
+  },
+  
+  toHaveLoggedInfo(received, expected) {
+    const infoLogs = global.console.info.mock.calls;
+    const pass = infoLogs.some(call => 
+      call.some(arg => 
+        typeof arg === 'string' && arg.includes(expected)
+      )
+    );
+    
+    if (pass) {
+      return {
+        message: () => `expected not to have logged info containing "${expected}"`,
+        pass: true
+      };
+    } else {
+      return {
+        message: () => `expected to have logged info containing "${expected}"`,
+        pass: false
+      };
+    }
+  },
+  
+  toBeWithinTimeLimit(received, limit) {
+    const pass = received <= limit;
+    
+    if (pass) {
+      return {
+        message: () => `expected ${received}ms not to be within ${limit}ms`,
+        pass: true
+      };
+    } else {
+      return {
+        message: () => `expected ${received}ms to be within ${limit}ms`,
+        pass: false
+      };
+    }
+  }
+});
+
+// Helper functions available in all tests
+global.TestHelpers = {
+  /**
+   * Create a temporary directory for tests
+   */
+  createTempDir() {
+    const fs = require('fs');
+    const path = require('path');
+    const os = require('os');
+    
+    return fs.mkdtempSync(path.join(os.tmpdir(), 'frigg-cli-test-'));
+  },
+  
+  /**
+   * Clean up temporary directory
+   */
+  cleanupTempDir(dirPath) {
+    const fs = require('fs');
+    
+    if (fs.existsSync(dirPath)) {
+      fs.rmSync(dirPath, { recursive: true, force: true });
+    }
+  },
+  
+  /**
+   * Create a mock package.json file
+   */
+  createMockPackageJson(overrides = {}) {
+    return JSON.stringify({
+      name: 'test-package',
+      version: '1.0.0',
+      main: 'index.js',
+      scripts: {
+        test: 'jest',
+        start: 'node index.js'
+      },
+      dependencies: {},
+      devDependencies: {},
+      ...overrides
+    }, null, 2);
+  },
+  
+  /**
+   * Create a mock frigg.config.json file
+   */
+  createMockFriggConfig(overrides = {}) {
+    return JSON.stringify({
+      stage: 'dev',
+      region: 'us-east-1',
+      profile: 'default',
+      backend: {
+        runtime: 'nodejs18.x',
+        timeout: 30,
+        memory: 128
+      },
+      ...overrides
+    }, null, 2);
+  },
+  
+  /**
+   * Wait for a specific amount of time
+   */
+  async delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  },
+  
+  /**
+   * Generate a random string for test data
+   */
+  randomString(length = 10) {
+    return Math.random().toString(36).substring(2, length + 2);
+  },
+  
+  /**
+   * Simulate file system structure
+   */
+  mockFileSystem(structure) {
+    const fs = require('fs');
+    
+    const originalExistsSync = fs.existsSync;
+    const originalReadFileSync = fs.readFileSync;
+    const originalWriteFileSync = fs.writeFileSync;
+    
+    fs.existsSync = jest.fn((path) => {
+      return structure.hasOwnProperty(path);
+    });
+    
+    fs.readFileSync = jest.fn((path) => {
+      if (structure.hasOwnProperty(path)) {
+        return structure[path];
+      }
+      throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+    });
+    
+    fs.writeFileSync = jest.fn((path, data) => {
+      structure[path] = data;
+    });
+    
+    return {
+      restore() {
+        fs.existsSync = originalExistsSync;
+        fs.readFileSync = originalReadFileSync;
+        fs.writeFileSync = originalWriteFileSync;
+      }
+    };
+  }
+};
+
+// Global timeout for all tests
+jest.setTimeout(30000);
+
+// Suppress specific warnings during tests
+// Note: console.warn is already mocked above, so we keep the mock
+// and just suppress certain warnings in the implementation
+const originalWarnMock = global.console.warn;
+global.console.warn = jest.fn((...args) => {
+  // Suppress specific warnings that are expected during testing
+  const message = args.join(' ');
+  if (message.includes('ExperimentalWarning') ||
+      message.includes('DeprecationWarning')) {
+    return;
+  }
+  // Still track the call in the mock
+});

package/frigg-cli/auth-command/CLAUDE.md

@@ -0,0 +1,293 @@
+# CLAUDE.md - Frigg Authenticator
+
+This file provides guidance to Claude Code when working with the Frigg Authenticator tool.
+
+## Overview
+
+The Frigg Authenticator is a CLI tool for testing API module authentication flows. It's part of `@friggframework/devtools` and enables developers to validate OAuth2 and API-Key authentication without deploying full Frigg infrastructure.
+
+## Directory Structure
+
+```
+auth-command/
+├── index.js                 # Main CLI command handler (test, list, get, delete)
+├── module-loader.js         # Dynamic module loading & validation
+├── credential-storage.js    # .frigg-credentials.json persistence
+├── oauth-callback-server.js # Local HTTP server for OAuth callbacks
+├── oauth-flow.js            # OAuth2 flow orchestration
+├── api-key-flow.js          # API-Key authentication flow
+├── json-schema-form.js      # Interactive JSON Schema form renderer (CLI prompts)
+├── auth-tester.js           # Run testAuthRequest & sample API calls
+├── utils/
+│   └── browser.js           # Cross-platform browser opening
+├── README.md                # User documentation
+└── CLAUDE.md                # This file - AI assistant guidance
+```
+
+## Key Files and Their Purpose
+
+### `index.js` - Command Handler
+Main entry point that exports `authCommand` object with methods:
+- `test(moduleName, options)` - Test authentication for a module
+- `list(options)` - List saved credentials
+- `get(moduleName, options)` - Retrieve credentials
+- `delete(moduleName, options)` - Remove credentials
+
+**When to modify:** Adding new subcommands or changing command behavior.
+
+### `module-loader.js` - Module Loading
+Handles dynamic loading of API modules from various sources:
+- Current directory (`.`)
+- Relative/absolute paths (`./path/to/module`)
+- Short names (`attio` → `@friggframework/api-module-attio`)
+- Full package names (`@friggframework/api-module-attio`)
+
+**Key functions:**
+- `loadModule(moduleIdentifier)` - Load and return `{definition, Api, modulePath}`
+- `validateModule(definition)` - Ensure module has required fields
+- `getAuthType(Api)` - Detect auth type (oauth2 or apiKey)
+
+**When to modify:** Supporting new module locations or validation rules.
+
+### `credential-storage.js` - Persistence
+Manages `.frigg-credentials.json` file:
+- Stores credentials per module
+- Supports global (`~/.frigg-credentials.json`) and local storage
+- Auto-adds to `.gitignore`
+
+**Key class:** `CredentialStorage`
+- `save(moduleName, credentials, authType)`
+- `get(moduleName)`
+- `list()`
+- `delete(moduleName)`
+- `deleteAll()`
+
+**When to modify:** Changing storage format or location logic.
+
+### `oauth-callback-server.js` - OAuth Server
+Local HTTP server that captures OAuth callbacks:
+- Listens on configurable port (default: 3333)
+- Handles `?code=` and `?error=` query params
+- Returns success/error HTML pages
+- Implements timeout handling
+
+**Key class:** `OAuthCallbackServer`
+- `start()` - Start the server
+- `waitForCode()` - Promise that resolves with `{code, state}`
+- `stop()` - Shutdown the server
+
+**When to modify:** Changing callback behavior or HTML responses.
+
+### `oauth-flow.js` - OAuth2 Orchestration
+Orchestrates the complete OAuth2 flow:
+1. Generate CSRF state token
+2. Create API instance with env params
+3. Get authorization URL
+4. Start callback server
+5. Open browser or print URL
+6. Wait for callback
+7. Verify state (CSRF protection)
+8. Exchange code for tokens via `getToken()`
+9. Fetch entity details via `getEntityDetails()`
+10. Return credentials object
+
+**Key function:** `runOAuthFlow(definition, ApiClass, options)`
+
+**When to modify:** Changing OAuth flow steps or adding features.
+
+### `api-key-flow.js` - API-Key Flow
+Handles API-Key authentication:
+1. Check for `getAuthorizationRequirements` in module definition
+2. If no API key provided and `getAuthorizationRequirements` exists, render JSON Schema form
+3. Create API instance
+4. Set API key via `setApiKey()` or similar
+5. Fetch entity details
+6. Return credentials object
+
+**Key function:** `runApiKeyFlow(definition, ApiClass, apiKey, options)`
+
+**When to modify:** Supporting different API key mechanisms or form rendering.
+
+### `json-schema-form.js` - Interactive Form Renderer
+Renders JSON Schema as interactive CLI prompts using `@inquirer/prompts`:
+1. Display form title from `jsonSchema.title`
+2. Iterate through `jsonSchema.properties`
+3. Show help text from `uiSchema[field]['ui:help']`
+4. Use password prompt for `ui:widget: 'password'` fields
+5. Validate required fields
+6. Return collected form data
+
+**Key function:** `renderJsonSchemaForm(jsonSchema, uiSchema)`
+
+**When to modify:** Adding new field types or UI schema options.
+
+**Example output:**
+```
+📝 Quo API Authorization
+
+  (Your Quo API key)
+  API Key: ********************************
+```
+
+### `auth-tester.js` - Verification
+Runs verification tests after authentication:
+1. Create fresh API instance with credentials
+2. Run `testAuthRequest` from module definition
+3. Try common sample API methods
+4. Verify credential properties are set
+
+**Key function:** `runAuthTests(definition, ApiClass, credentials, options)`
+
+**When to modify:** Adding verification steps or sample methods.
+
+### `utils/browser.js` - Browser Opening
+Cross-platform browser opening utility:
+- macOS: `open`
+- Windows: `start`
+- Linux: `xdg-open`
+
+**Key function:** `openBrowser(url)`
+
+## Integration with Frigg CLI
+
+The authenticator is registered in `frigg-cli/index.js`:
+
+```javascript
+const { authCommand } = require('./auth-command');
+
+const authProgram = program
+    .command('auth')
+    .description('Test API module authentication');
+
+authProgram
+    .command('test <module>')
+    .action(authCommand.test);
+// ... more subcommands
+```
+
+## Common Development Tasks
+
+### Adding a New Subcommand
+
+1. Add handler method in `auth-command/index.js`
+2. Register in `frigg-cli/index.js` under `authProgram`
+3. Update README.md with usage docs
+
+### Supporting a New Auth Type
+
+1. Create new flow file (e.g., `basic-auth-flow.js`)
+2. Update `getAuthType()` in `module-loader.js`
+3. Add case in `test()` handler in `index.js`
+
+### Changing Credential Format
+
+1. Update `save()` and `get()` in `credential-storage.js`
+2. Consider migration for existing credentials
+3. Update `_meta.version` for format versioning
+
+### Adding Verification Steps
+
+1. Modify `runAuthTests()` in `auth-tester.js`
+2. Add new sample methods to check
+3. Update verbose output
+
+## Testing
+
+### Manual Testing
+
+```bash
+# Test with a real module
+cd /path/to/api-module-attio
+export ATTIO_CLIENT_ID=xxx
+export ATTIO_CLIENT_SECRET=xxx
+export ATTIO_SCOPE="read:objects"
+export REDIRECT_URI="http://localhost:3333"
+node /path/to/frigg-cli/index.js auth test . --verbose
+```
+
+### Unit Testing
+
+Tests should be added to `frigg-cli/test/auth-command.test.js`:
+- Test module loading with various paths
+- Test credential storage operations
+- Mock OAuth callback server responses
+- Test error handling
+
+## Error Handling Patterns
+
+### User-Friendly Errors
+
+```javascript
+throw new Error(
+    `Port ${port} is already in use.\n` +
+    `Try using a different port: frigg auth test <module> --port <different-port>`
+);
+```
+
+### Validation Errors
+
+```javascript
+const errors = [];
+if (!definition.moduleName) {
+    errors.push('Missing required field: moduleName');
+}
+if (errors.length > 0) {
+    throw new Error(`Module validation failed:\n${errors.map(e => `  - ${e}`).join('\n')}`);
+}
+```
+
+## Dependencies
+
+External packages used:
+- `chalk` - Terminal colors
+- `commander` - CLI framework (via parent)
+- `@inquirer/prompts` - Interactive CLI prompts (input, password)
+
+Node.js built-ins:
+- `http` - Callback server
+- `url` - URL parsing
+- `fs` - File system
+- `path` - Path utilities
+- `os` - OS info
+- `crypto` - State token generation
+- `child_process` - Browser opening
+- `readline` - User confirmation
+
+## Security Considerations
+
+1. **State Parameter**: CSRF protection via random state token
+2. **Local Only**: Callback server only binds to localhost
+3. **No Credential Logging**: Sensitive values are masked in output
+4. **Gitignore Integration**: Auto-adds credentials file to .gitignore
+5. **Sanitization**: Client secrets removed from stored apiParams
+
+## Common Issues
+
+### Module Not Loading
+
+Check:
+- Module exports `{Definition}` or `{definition}`
+- Definition has `API` class
+- `require('dotenv').config()` is called in definition.js
+
+### OAuth Flow Failing
+
+Check:
+- Environment variables are set correctly
+- Redirect URI matches callback server port
+- OAuth credentials are valid
+- Scopes are correct
+
+### Credentials Not Persisting
+
+Check:
+- Write permissions on target directory
+- File isn't gitignored in a way that prevents reading
+- Storage path detection is correct
+
+## Related Documentation
+
+- [Frigg Framework CLAUDE.md](../../CLAUDE.md)
+- [API Module Library](https://github.com/friggframework/api-module-library)
+- [OAuth2Requester](../../../core/modules/requester/oauth-2.js)
+- [ApiKeyRequester](../../../core/modules/requester/ApiKeyRequester.js)