@friggframework/devtools 2.0.0-next.4 → 2.0.0-next.41

package/management-ui/.eslintrc.js

@@ -0,0 +1,22 @@
+module.exports = {
+  root: true,
+  env: { browser: true, es2020: true },
+  extends: [
+    'eslint:recommended',
+    '@eslint/js/recommended',
+    'plugin:react/recommended',
+    'plugin:react/jsx-runtime',
+    'plugin:react-hooks/recommended',
+  ],
+  ignorePatterns: ['dist', '.eslintrc.js'],
+  parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
+  settings: { react: { version: '18.3' } },
+  plugins: ['react-refresh'],
+  rules: {
+    'react/jsx-no-target-blank': 'off',
+    'react-refresh/only-export-components': [
+      'warn',
+      { allowConstantExport: true },
+    ],
+  },
+}

package/management-ui/README.md

@@ -0,0 +1,203 @@
+# Frigg Management UI
+
+A modern React-based management interface for Frigg development environment. Built with Vite, React, and Tailwind CSS, this application provides developers with a comprehensive dashboard to manage integrations, users, connections, and environment variables.
+
+## Features
+
+- **Dashboard**: Server control, metrics, and activity monitoring
+- **Integration Discovery**: Browse, install, and manage Frigg integrations
+- **Environment Management**: Configure environment variables and settings
+- **User Management**: Create and manage test users
+- **Connection Management**: Monitor and manage integration connections
+- **Real-time Updates**: WebSocket-based live updates
+- **Responsive Design**: Mobile-friendly interface
+- **Error Boundaries**: Robust error handling
+
+## Tech Stack
+
+- **React 18.3**: Modern React with hooks and functional components
+- **Vite**: Fast development and build tooling
+- **React Router**: Client-side routing
+- **Tailwind CSS**: Utility-first CSS framework
+- **Lucide React**: Modern icon library
+- **Socket.io**: Real-time communication
+- **Axios**: HTTP client
+- **@friggframework/ui**: Shared UI components
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 16+ and npm
+- Running Frigg backend server
+
+### Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server (frontend only)
+npm run dev
+
+# Start both frontend and backend
+npm run dev:server
+
+# Build for production
+npm run build
+```
+
+### Available Scripts
+
+- `npm run dev` - Start Vite development server
+- `npm run dev:server` - Start both frontend and backend concurrently
+- `npm run build` - Build for production
+- `npm run preview` - Preview production build
+- `npm run server` - Start backend server only
+- `npm run server:dev` - Start backend server with nodemon
+- `npm run lint` - Run ESLint
+- `npm run lint:fix` - Fix ESLint issues
+- `npm run typecheck` - Run TypeScript type checking
+
+## Project Structure
+
+```
+src/
+├── components/          # Reusable UI components
+│   ├── Button.jsx      # Custom button component
+│   ├── Card.jsx        # Card container components
+│   ├── ErrorBoundary.jsx
+│   ├── IntegrationCard.jsx
+│   ├── Layout.jsx      # Main layout component
+│   ├── LoadingSpinner.jsx
+│   ├── StatusBadge.jsx
+│   └── index.js        # Component exports
+├── hooks/              # React hooks
+│   ├── useFrigg.jsx    # Main Frigg state management
+│   └── useSocket.jsx   # WebSocket connection
+├── pages/              # Page components
+│   ├── Dashboard.jsx   # Main dashboard
+│   ├── Integrations.jsx
+│   ├── Environment.jsx
+│   ├── Users.jsx
+│   └── Connections.jsx
+├── services/           # API services
+│   └── api.js          # Axios configuration
+├── utils/              # Utility functions
+│   └── cn.js           # Class name utility
+├── App.jsx             # Root component
+├── main.jsx            # Application entry point
+└── index.css           # Global styles
+
+server/
+├── api/                # Backend API routes
+├── middleware/         # Express middleware
+├── utils/              # Server utilities
+├── websocket/          # WebSocket handlers
+└── index.js            # Server entry point
+```
+
+## Component Architecture
+
+### Layout Components
+- **Layout**: Main application layout with responsive sidebar
+- **ErrorBoundary**: Catches and displays errors gracefully
+
+### UI Components
+- **Button**: Customizable button with variants and sizes
+- **Card**: Container components for content sections
+- **StatusBadge**: Displays server status with color coding
+- **LoadingSpinner**: Loading indicators
+- **IntegrationCard**: Rich integration display component
+
+### State Management
+- **useFrigg**: Central state management for Frigg data
+- **useSocket**: WebSocket connection and real-time updates
+
+## API Integration
+
+The management UI communicates with the Frigg backend through:
+
+1. **REST API**: Standard CRUD operations
+2. **WebSocket**: Real-time updates and notifications
+
+### API Endpoints
+
+- `GET /api/frigg/status` - Server status
+- `POST /api/frigg/start` - Start Frigg server
+- `POST /api/frigg/stop` - Stop Frigg server
+- `GET /api/integrations` - List integrations
+- `POST /api/integrations/install` - Install integration
+- `GET /api/environment` - Environment variables
+- `PUT /api/environment` - Update environment variables
+- `GET /api/users` - List test users
+- `POST /api/users` - Create test user
+- `GET /api/connections` - List connections
+
+## Styling
+
+This project uses Tailwind CSS for styling with:
+
+- **Design System**: Consistent spacing, colors, and typography
+- **Responsive Design**: Mobile-first approach
+- **Component Variants**: Button and component style variants
+- **Dark Mode Ready**: CSS custom properties for theming
+
+### Custom Utilities
+
+- `cn()`: Utility for combining Tailwind classes with conditional logic
+
+## Error Handling
+
+- **Error Boundaries**: React error boundaries catch component errors
+- **API Error Handling**: Axios interceptors handle API errors
+- **Loading States**: Loading spinners and disabled states
+- **Validation**: Form validation and user feedback
+
+## Development
+
+### Code Style
+
+- **ESLint**: Linting with React and React Hooks rules
+- **Prettier**: Code formatting (recommended)
+- **TypeScript Ready**: Prepared for TypeScript migration
+
+### Best Practices
+
+- Functional components with hooks
+- Component composition over inheritance
+- Separation of concerns (UI, state, logic)
+- Error boundaries for robustness
+- Loading states for better UX
+- Responsive design principles
+
+## Building and Deployment
+
+```bash
+# Build for production
+npm run build
+
+# Preview production build
+npm run preview
+```
+
+The build output will be in the `dist/` directory and can be served by any static file server.
+
+## Environment Variables
+
+The application automatically detects the environment:
+
+- **Development**: API calls to `http://localhost:3001`
+- **Production**: API calls to the same origin
+
+## Contributing
+
+1. Follow the existing code style and patterns
+2. Add error handling for new features
+3. Include loading states for async operations
+4. Write tests for new components (when testing is set up)
+5. Update documentation for significant changes
+
+## License
+
+This project is part of the Frigg Framework and follows the same licensing terms.

package/management-ui/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.js",
+    "css": "src/index.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

package/management-ui/docs/phase2-integration-guide.md

@@ -0,0 +1,320 @@
+# Phase 2 Integration Guide
+
+## Overview
+
+This guide covers the complete integration of all Phase 2 features for the Frigg Management UI as specified in RFC 0001. Phase 2 introduces core features that transform the developer experience with visual tools for integration management, testing, and deployment.
+
+## Phase 2 Core Features
+
+### 1. Integration Discovery and Installation
+
+The integration discovery system connects to the npm registry to find and install @friggframework modules.
+
+#### Key Components:
+- **IntegrationDiscoveryService**: Searches npm registry for Frigg integrations
+- **IntegrationInstallerService**: Handles package installation and dependency management
+- **UI Components**: Visual interface for browsing and installing integrations
+
+#### Usage:
+```javascript
+// Discover integrations
+const discoveries = await discoveryService.searchIntegrations({
+  query: 'hubspot',
+  limit: 20
+});
+
+// Install integration
+const result = await installerService.installIntegration({
+  packageName: '@friggframework/api-module-hubspot'
+});
+```
+
+### 2. Dummy User Management System
+
+Create and manage test users for development and testing purposes.
+
+#### Features:
+- Generate unique test IDs for each user
+- Create OAuth credentials for testing
+- Bulk user creation support
+- Complete isolation from production data
+
+#### API Endpoints:
+- `POST /api/users/dummy` - Create a dummy user
+- `GET /api/users/dummy` - List all dummy users
+- `POST /api/users/dummy/:id/credentials` - Generate test credentials
+- `POST /api/users/dummy/bulk` - Create multiple users
+
+### 3. Connection/Entity Management
+
+Manage connections between users and integrations with full entity synchronization.
+
+#### Capabilities:
+- Create and manage user-integration connections
+- Health monitoring for active connections
+- Entity CRUD operations
+- Bulk synchronization support
+
+#### Connection Lifecycle:
+1. Create connection with user credentials
+2. Test connection health
+3. Manage entities (contacts, deals, messages, etc.)
+4. Monitor connection status
+5. Handle refresh/reconnection
+
+### 4. Environment Variable Editor
+
+Visual interface for managing environment variables across development and production.
+
+#### Features:
+- Read and display current variables
+- Mask sensitive values (passwords, keys, secrets)
+- Validate variable names
+- Differentiate local vs production environments
+- Bulk update support
+
+#### Security:
+- Automatic masking of sensitive values
+- Validation to prevent invalid variable names
+- Production update confirmation required
+- AWS Parameter Store integration for production
+
+## Integration Workflows
+
+### Complete Integration Setup Flow
+
+```javascript
+const workflow = await phase2Workflows.setupIntegration('hubspot', {
+  config: {
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret'
+  },
+  testUserName: 'HubSpot Test User',
+  environment: 'development'
+});
+```
+
+This workflow automatically:
+1. Discovers integration details
+2. Installs the package
+3. Configures the integration
+4. Creates a test user
+5. Generates credentials
+6. Creates a connection
+7. Tests the connection
+8. Sets up environment variables
+
+### Bulk Integration Management
+
+```javascript
+const bulkResult = await phase2Workflows.bulkIntegrationSetup([
+  { name: 'slack', options: { /* config */ } },
+  { name: 'salesforce', options: { /* config */ } },
+  { name: 'stripe', options: { /* config */ } }
+], {
+  batchSize: 3 // Process in parallel
+});
+```
+
+### Development Environment Setup
+
+```javascript
+const devEnv = await phase2Workflows.setupDevelopmentEnvironment({
+  projectType: 'saas',
+  integrations: ['stripe', 'hubspot', 'slack'],
+  testUserCount: 10,
+  mockDataTypes: ['contacts', 'messages', 'payments']
+});
+```
+
+## Testing Phase 2 Features
+
+### Integration Tests
+
+Run the comprehensive integration test suite:
+
+```bash
+npm run test:integration
+```
+
+Key test areas:
+- End-to-end user flows
+- WebSocket real-time updates
+- Concurrent operation handling
+- Error recovery
+- Data consistency
+
+### Performance Benchmarks
+
+Run performance benchmarks:
+
+```bash
+npm run benchmark:phase2
+```
+
+Benchmark metrics:
+- Integration discovery speed
+- Installation throughput
+- API response times
+- WebSocket latency
+- Memory usage under load
+- Concurrent user capacity
+
+### Validation Tests
+
+Ensure RFC compliance:
+
+```bash
+npm run test:validation
+```
+
+Validates:
+- All RFC requirements are met
+- Security requirements
+- Performance targets
+- API contracts
+- Migration compatibility
+
+## Performance Optimization
+
+### Caching Strategy
+
+The discovery service implements a 1-hour cache for npm queries:
+- Cold start: First request fetches from npm
+- Cached: Subsequent requests use in-memory cache
+- Cache invalidation: Manual or time-based
+
+### Batch Processing
+
+For optimal performance with multiple operations:
+- Use bulk endpoints when available
+- Process in configurable batch sizes
+- Implement proper error handling per batch
+
+### WebSocket Updates
+
+Real-time updates for long-running operations:
+- Installation progress
+- Connection status changes
+- Environment updates
+- Error notifications
+
+## Security Considerations
+
+### Environment Variables
+- Automatic masking of sensitive values
+- Patterns detected: PASSWORD, SECRET, KEY, TOKEN, etc.
+- Read-only access for discovery operations
+- Production updates require explicit confirmation
+
+### Test Data Isolation
+- All dummy users marked with `isDummy: true`
+- Test IDs include 'test' prefix
+- Separate storage from production data
+- No cross-contamination possible
+
+### Input Validation
+- Variable name validation (alphanumeric + underscore)
+- Package name verification
+- Credential format checking
+- SQL injection prevention
+
+## Migration from create-frigg-app
+
+### Automated Migration
+
+```javascript
+const migration = await phase2Workflows.migrateProject('/path/to/project', {
+  preserveCustom: true,
+  integrationMapping: {
+    'old-integration': 'new-integration'
+  }
+});
+```
+
+### Manual Migration Steps
+
+1. **Backup existing project**
+2. **Update dependencies**:
+   ```json
+   {
+     "devDependencies": {
+       "@friggframework/cli": "latest"
+     }
+   }
+   ```
+3. **Run migration command**:
+   ```bash
+   frigg migrate --from-create-frigg-app
+   ```
+4. **Verify integration configurations**
+5. **Update environment variables**
+6. **Test all connections**
+
+## Troubleshooting
+
+### Common Issues
+
+#### Integration Discovery Fails
+- Check network connectivity
+- Verify npm registry access
+- Clear discovery cache
+- Check for proxy settings
+
+#### Connection Test Failures
+- Verify credentials are correct
+- Check integration configuration
+- Review API rate limits
+- Inspect WebSocket connection
+
+#### Environment Variable Issues
+- Ensure valid variable names
+- Check file permissions for .env
+- Verify AWS credentials for production
+- Look for conflicting variables
+
+### Debug Mode
+
+Enable debug logging:
+```bash
+DEBUG=frigg:* npm run dev:server
+```
+
+### Health Checks
+
+Monitor system health:
+```javascript
+// API endpoint
+GET /api/health
+
+// Returns
+{
+  "status": "healthy",
+  "services": {
+    "discovery": "operational",
+    "installer": "operational",
+    "websocket": "connected",
+    "environment": "configured"
+  }
+}
+```
+
+## Best Practices
+
+1. **Use Workflows**: Leverage the provided workflows for complex operations
+2. **Monitor Performance**: Regularly run benchmarks to ensure optimal performance
+3. **Test Thoroughly**: Use the comprehensive test suites before deployment
+4. **Handle Errors**: Implement proper error handling for all async operations
+5. **Cache Wisely**: Use caching for frequently accessed data
+6. **Secure Sensitive Data**: Always mask sensitive environment variables
+7. **Document Custom Integrations**: Maintain clear documentation for custom work
+
+## Next Steps
+
+After Phase 2 implementation:
+
+1. **Phase 3**: Advanced features including production monitoring
+2. **Phase 4**: Multi-framework UI support
+3. **Phase 5**: Complete migration and deprecation of create-frigg-app
+
+For questions or issues, refer to the [Frigg documentation](https://docs.frigg.dev) or open an issue on GitHub.

package/management-ui/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Frigg Management UI</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>