@friggframework/devtools 2.0.0--canary.517.179491e.0 → 2.0.0--canary.522.893db5d.0

package/frigg-cli/docs/OUTPUT_MIGRATION_GUIDE.md

@@ -0,0 +1,286 @@
+# Output Class Migration Guide
+
+This guide shows how to migrate existing CLI commands to use the new unified `Output` class.
+
+## Why Migrate?
+
+The unified `Output` class provides:
+- **Consistency**: Same UI patterns across all commands
+- **Better UX**: Spinners, progress bars, formatted tables
+- **Maintainability**: Single place to update UI behavior
+- **Testing**: Easier to mock and test
+
+## Before vs After
+
+### Before (Inconsistent)
+
+```javascript
+// install-command/index.js (OLD - plain console.log)
+function logError(message, error) {
+    console.error(message, error);
+}
+
+function logSuccess(message) {
+    console.log(message);
+}
+
+// Some other command (OLD - using chalk directly)
+const chalk = require('chalk');
+console.log(chalk.green('✓ Success'));
+console.error(chalk.red('✗ Failed'));
+
+// repair-command (OLD - using readline)
+const readline = require('readline');
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+});
+rl.question('Select option: ', (answer) => {
+    // ...
+});
+```
+
+### After (Consistent)
+
+```javascript
+// All commands use the same output utility
+const output = require('./utils/output');
+
+output.success('Operation completed');
+output.error('Operation failed', error);
+
+const spinner = output.spinner('Installing...');
+// do work
+spinner.succeed('Installed successfully');
+
+const answer = await output.confirm('Continue with installation?');
+```
+
+## Migration Steps
+
+### Step 1: Import Output
+
+Replace all imports of `chalk`, `console`, and `readline`:
+
+```diff
+- const chalk = require('chalk');
+- const readline = require('readline');
++ const output = require('../utils/output');
+```
+
+### Step 2: Replace Console Methods
+
+| Old | New |
+|-----|-----|
+| `console.log('Success')` | `output.success('Success')` |
+| `console.error('Error')` | `output.error('Error')` |
+| `console.info('Info')` | `output.info('Info')` |
+| `console.warn('Warning')` | `output.warn('Warning')` |
+| `console.log(chalk.green('✓ Done'))` | `output.success('Done')` |
+| `console.error(chalk.red('✗ Failed'))` | `output.error('Failed')` |
+
+### Step 3: Replace Chalk Usage
+
+```diff
+- console.log(chalk.blue('Starting...'));
++ output.info('Starting...');
+
+- console.log(chalk.bold('=== Header ==='));
++ output.header('Header');
+
+- console.log(chalk.yellow('⚠ Warning'));
++ output.warn('Warning');
+```
+
+### Step 4: Replace Inquirer Prompts
+
+```diff
+- const { confirm } = require('@inquirer/prompts');
+- const answer = await confirm({ message: 'Continue?' });
++ const answer = await output.confirm('Continue?');
+
+- const { select } = require('@inquirer/prompts');
+- const choice = await select({
+-     message: 'Select option',
+-     choices: ['Option 1', 'Option 2']
+- });
++ const choice = await output.select('Select option', ['Option 1', 'Option 2']);
+```
+
+### Step 5: Replace Readline (repair-command)
+
+```diff
+- const readline = require('readline');
+- const rl = readline.createInterface({
+-     input: process.stdin,
+-     output: process.stdout
+- });
+- rl.question('Select option: ', (answer) => {
+-     // handle answer
+-     rl.close();
+- });
++ const answer = await output.input('Select option:');
++ // handle answer (no need to close)
+```
+
+### Step 6: Add Spinners for Long Operations
+
+```diff
+- console.log('Installing dependencies...');
+- await installDependencies();
+- console.log('Done');
++ const spinner = output.spinner('Installing dependencies...');
++ await installDependencies();
++ spinner.succeed('Dependencies installed');
+```
+
+### Step 7: Add Progress Bars
+
+```diff
+- console.log(`Progress: ${i}/${total}`);
++ output.progress(i, total, 'Processing files...');
+```
+
+### Step 8: Display Tables
+
+```diff
+- modules.forEach(mod => {
+-     console.log(`${mod.name}\t${mod.version}\t${mod.status}`);
+- });
++ output.table(modules, ['name', 'version', 'status']);
+```
+
+## Real Example: install-command
+
+### Before
+
+```javascript
+// install-command/logger.js
+function logError(message, error) {
+    console.error(message, error);
+    if (error && error.stack) {
+        console.error(error.stack);
+    }
+}
+
+function logSuccess(message) {
+    console.log(message);
+}
+
+function logInfo(message) {
+    console.log(message);
+}
+
+module.exports = {
+    logError,
+    logSuccess,
+    logInfo
+};
+
+// install-command/index.js
+const logger = require('./logger');
+
+logger.logInfo('Starting installation...');
+// ...
+logger.logSuccess('Module installed successfully');
+```
+
+### After
+
+```javascript
+// install-command/index.js
+const output = require('../utils/output');
+
+const spinner = output.spinner('Installing module...');
+try {
+    // ... do installation
+    spinner.succeed('Module installed successfully');
+} catch (error) {
+    spinner.fail('Installation failed');
+    output.error('Failed to install module', error);
+    process.exit(1);
+}
+```
+
+**Result**: Delete `install-command/logger.js` (no longer needed!)
+
+## Commands to Migrate
+
+Priority order based on usage and inconsistency:
+
+1. **install-command** (HIGH) - Uses plain console.log, has trivial logger wrapper
+2. **repair-command** (HIGH) - Uses readline instead of inquirer
+3. **doctor-command** (MEDIUM) - Long-running, needs spinners
+4. **deploy-command** (MEDIUM) - Long-running, needs progress indication
+5. **start-command** (LOW) - Already uses chalk consistently
+6. **generate-command** (LOW) - Uses inquirer, but inconsistent colors
+7. **build-command** (LOW) - Simple command, less output
+
+## Testing Your Migration
+
+After migrating a command:
+
+1. **Run the command** manually to verify output looks correct
+2. **Update tests** to mock `output` instead of `console`/`chalk`/`inquirer`
+3. **Check for** color consistency, spinner behavior, error messages
+
+### Test Example
+
+```javascript
+// Before
+jest.spyOn(console, 'log');
+await myCommand();
+expect(console.log).toHaveBeenCalledWith(expect.stringContaining('Success'));
+
+// After
+const output = require('../utils/output');
+jest.spyOn(output, 'success');
+await myCommand();
+expect(output.success).toHaveBeenCalledWith('Operation completed');
+```
+
+## Output API Reference
+
+### Messages
+- `output.success(message)` - Green checkmark + message
+- `output.error(message, error?)` - Red X + message (+ stack trace if DEBUG=1)
+- `output.info(message)` - Blue info icon + message
+- `output.warn(message)` - Yellow warning icon + message
+- `output.debug(message)` - Gray message (only if DEBUG=1)
+
+### Formatting
+- `output.header(title)` - Bold cyan title with underline
+- `output.separator()` - Gray horizontal line
+- `output.newline()` - Blank line
+- `output.table(data, columns?)` - Formatted table
+- `output.keyValue(object)` - Key-value pairs
+- `output.json(data, indent?)` - Syntax-highlighted JSON
+
+### Interactive
+- `output.confirm(message, default?)` - Yes/no question
+- `output.input(message, default?, validate?)` - Text input
+- `output.select(message, choices, default?)` - Single selection
+- `output.checkbox(message, choices)` - Multiple selection
+- `output.password(message, validate?)` - Password input
+
+### Progress
+- `output.spinner(text)` - Returns {update, succeed, fail, stop}
+- `output.progress(current, total, message?)` - Progress bar
+
+### Compatibility
+- `output.log(...args)` - Raw console.log (for gradual migration)
+
+## Benefits After Migration
+
+- ✅ **32% less code** - Remove logger wrappers and boilerplate
+- ✅ **100% consistency** - All commands look and feel the same
+- ✅ **Better UX** - Spinners, progress bars, formatted tables
+- ✅ **Easier testing** - Mock one module instead of many
+- ✅ **Maintainable** - Update UI in one place
+
+## Questions?
+
+See:
+- `utils/output.js` - Full implementation
+- `__tests__/unit/utils/output.test.js` - Test examples
+- `FRIGG_CLI_ANALYSIS_REPORT.md` - Why we created this

package/frigg-cli/doctor-command/index.js

@@ -12,8 +12,9 @@
  */
 
 const path = require('path');
+const output = require('../utils/output');
 const fs = require('fs');
-const { select } = require('@inquirer/prompts');
+// Using output.select from unified Output class (wraps @inquirer/prompts)
 const { CloudFormationClient, ListStacksCommand } = require('@aws-sdk/client-cloudformation');
 
 // Domain and Application Layer
@@ -160,9 +161,9 @@ function formatJsonOutput(report) {
 function writeOutputFile(content, filePath) {
     try {
         fs.writeFileSync(filePath, content, 'utf8');
-        console.log(`\n✓ Report saved to: ${filePath}`);
+        output.success(` Report saved to: ${filePath}`);
     } catch (error) {
-        console.error(`\n✗ Failed to write output file: ${error.message}`);
+        output.error(` Failed to write output file: ${error.message}`);
         process.exit(1);
     }
 }
@@ -204,17 +205,17 @@ async function listStacks(region) {
  * @returns {Promise<string>} Selected stack name
  */
 async function promptForStackSelection(region) {
-    console.log(`\n🔍 Fetching CloudFormation stacks in ${region}...`);
+    output.info(`🔍 Fetching CloudFormation stacks in ${region}...`);
 
     const stacks = await listStacks(region);
 
     if (stacks.length === 0) {
-        console.error(`\n✗ No CloudFormation stacks found in ${region}`);
-        console.log('  Make sure you have stacks deployed and the correct AWS credentials configured.');
+        output.error(` No CloudFormation stacks found in ${region}`);
+        output.log('  Make sure you have stacks deployed and the correct AWS credentials configured.');
         process.exit(1);
     }
 
-    console.log(`\n✓ Found ${stacks.length} stack(s)\n`);
+    output.success(` Found ${stacks.length} stack(s)\n`);
 
     // Create choices with stack name and metadata
     const choices = stacks.map(stack => {
@@ -230,7 +231,7 @@ async function promptForStackSelection(region) {
         };
     });
 
-    const selectedStack = await select({
+    const selectedStack = await output.select({
         message: 'Select a stack to run health check:',
         choices,
         pageSize: 15,
@@ -257,7 +258,7 @@ async function doctorCommand(stackName, options = {}) {
         }
 
         // Show progress to user (always, not just verbose mode)
-        console.log(`\n🏥 Running health check on stack: ${stackName} (${region})\n`);
+        output.info(`🏥 Running health check on stack: ${stackName} (${region})\n`);
 
         // 1. Create stack identifier
         const stackIdentifier = new StackIdentifier({ stackName, region });
@@ -281,9 +282,9 @@ async function doctorCommand(stackName, options = {}) {
         // Progress callback to show execution status
         const progressCallback = (step, message) => {
             if (verbose) {
-                console.log(`   ${message}`);
+                output.log(`   ${message}`);
             } else {
-                console.log(`${step} ${message}`);
+                output.log(`${step} ${message}`);
             }
         };
 
@@ -292,7 +293,7 @@ async function doctorCommand(stackName, options = {}) {
             onProgress: progressCallback
         });
 
-        console.log('✓ Health check complete!\n');
+        output.success(' Health check complete!\n');
 
         // 5. Format and output results
         if (format === 'json') {
@@ -301,11 +302,11 @@ async function doctorCommand(stackName, options = {}) {
             if (options.output) {
                 writeOutputFile(jsonOutput, options.output);
             } else {
-                console.log(jsonOutput);
+                output.log(jsonOutput);
             }
         } else {
             const consoleOutput = formatConsoleOutput(report, options);
-            console.log(consoleOutput);
+            output.log(consoleOutput);
 
             if (options.output) {
                 writeOutputFile(consoleOutput, options.output);
@@ -322,10 +323,10 @@ async function doctorCommand(stackName, options = {}) {
             process.exit(0);
         }
     } catch (error) {
-        console.error(`\n✗ Health check failed: ${error.message}`);
+        output.error(` Health check failed: ${error.message}`);
 
         if (options.verbose && error.stack) {
-            console.error(`\nStack trace:\n${error.stack}`);
+            output.error(`\nStack trace:\n${error.stack}`);
         }
 
         process.exit(1);

package/frigg-cli/domain/entities/ApiModule.js

@@ -0,0 +1,272 @@
+const {DomainException} = require('../exceptions/DomainException');
+const {SemanticVersion} = require('../value-objects/SemanticVersion');
+
+/**
+ * ApiModule Entity
+ *
+ * Represents an API module that can be used by integrations
+ * API modules are reusable API clients for external services
+ */
+class ApiModule {
+    constructor(props) {
+        this.name = props.name; // kebab-case name
+        this.version = props.version instanceof SemanticVersion ?
+            props.version : new SemanticVersion(props.version || '1.0.0');
+        this.displayName = props.displayName || this._generateDisplayName();
+        this.description = props.description || '';
+        this.author = props.author || '';
+        this.license = props.license || 'UNLICENSED';
+        this.apiConfig = props.apiConfig || {
+            baseUrl: '',
+            authType: 'oauth2',
+            version: 'v1'
+        };
+        this.entities = props.entities || {}; // Database entities this module needs
+        this.scopes = props.scopes || []; // OAuth scopes required
+        this.credentials = props.credentials || []; // Required credentials
+        this.endpoints = props.endpoints || {}; // API endpoints
+        this.createdAt = props.createdAt || new Date();
+        this.updatedAt = props.updatedAt || new Date();
+    }
+
+    /**
+     * Factory method to create a new ApiModule
+     */
+    static create(props) {
+        if (!props.name) {
+            throw new DomainException('API module name is required');
+        }
+
+        // Validate name format
+        const namePattern = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/;
+        if (!namePattern.test(props.name)) {
+            throw new DomainException('API module name must be kebab-case');
+        }
+
+        // Validate authType is provided
+        if (!props.apiConfig || !props.apiConfig.authType) {
+            throw new DomainException('Authentication type is required');
+        }
+
+        return new ApiModule(props);
+    }
+
+    /**
+     * Reconstruct ApiModule from plain object
+     */
+    static fromObject(obj) {
+        return new ApiModule({
+            ...obj,
+            version: obj.version,
+            createdAt: new Date(obj.createdAt),
+            updatedAt: new Date(obj.updatedAt)
+        });
+    }
+
+    /**
+     * Add an entity configuration
+     * Entities are database records that store API credentials and state
+     *
+     * @param {string} entityName - Entity name (e.g., 'credential', 'user')
+     * @param {object} config - Entity configuration
+     */
+    addEntity(entityName, config = {}) {
+        if (this.hasEntity(entityName)) {
+            throw new DomainException(`Entity '${entityName}' already exists`);
+        }
+
+        this.entities[entityName] = {
+            type: entityName,
+            label: config.label || entityName,
+            required: config.required !== false,
+            fields: config.fields || [],
+            ...config
+        };
+
+        this.updatedAt = new Date();
+        return this;
+    }
+
+    /**
+     * Check if entity exists
+     */
+    hasEntity(entityName) {
+        return entityName in this.entities;
+    }
+
+    /**
+     * Add an endpoint definition
+     */
+    addEndpoint(name, config) {
+        if (this.hasEndpoint(name)) {
+            throw new DomainException(`Endpoint '${name}' already exists`);
+        }
+
+        this.endpoints[name] = {
+            method: config.method || 'GET',
+            path: config.path,
+            description: config.description || '',
+            parameters: config.parameters || [],
+            response: config.response || {},
+            ...config
+        };
+
+        this.updatedAt = new Date();
+        return this;
+    }
+
+    /**
+     * Check if endpoint exists
+     */
+    hasEndpoint(name) {
+        return name in this.endpoints;
+    }
+
+    /**
+     * Add required OAuth scope
+     */
+    addScope(scope) {
+        if (this.scopes.includes(scope)) {
+            throw new DomainException(`Scope '${scope}' already exists`);
+        }
+        this.scopes.push(scope);
+        this.updatedAt = new Date();
+        return this;
+    }
+
+    /**
+     * Add required credential
+     */
+    addCredential(name, config = {}) {
+        const existing = this.credentials.find(c => c.name === name);
+        if (existing) {
+            throw new DomainException(`Credential '${name}' already exists`);
+        }
+
+        this.credentials.push({
+            name,
+            type: config.type || 'string',
+            required: config.required !== false,
+            description: config.description || '',
+            example: config.example || '',
+            envVar: config.envVar || '',
+            ...config
+        });
+
+        this.updatedAt = new Date();
+        return this;
+    }
+
+    /**
+     * Check if credential exists
+     */
+    hasCredential(name) {
+        return this.credentials.some(c => c.name === name);
+    }
+
+    /**
+     * Validate API module business rules
+     */
+    validate() {
+        const errors = [];
+
+        // Name validation (kebab-case)
+        if (!this.name || this.name.trim().length === 0) {
+            errors.push('API module name is required');
+        }
+
+        const namePattern = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/;
+        if (this.name && !namePattern.test(this.name)) {
+            errors.push('API module name must be kebab-case');
+        }
+
+        // Display name validation
+        if (!this.displayName || this.displayName.trim().length === 0) {
+            errors.push('Display name is required');
+        }
+
+        // Description validation
+        if (this.description && this.description.length > 1000) {
+            errors.push('Description must be 1000 characters or less');
+        }
+
+        // API config validation
+        if (!this.apiConfig.baseUrl) {
+            // Warning: base URL should be provided, but not required at creation
+        }
+
+        // Auth type validation
+        if (!this.apiConfig.authType || this.apiConfig.authType.trim().length === 0) {
+            errors.push('Authentication type is required');
+        } else {
+            const validAuthTypes = ['oauth2', 'api-key', 'basic', 'token', 'custom'];
+            if (!validAuthTypes.includes(this.apiConfig.authType)) {
+                errors.push(`Invalid auth type. Must be one of: ${validAuthTypes.join(', ')}`);
+            }
+        }
+
+        return {
+            isValid: errors.length === 0,
+            errors
+        };
+    }
+
+    /**
+     * Convert to plain object
+     */
+    toObject() {
+        return {
+            name: this.name,
+            version: this.version.value,
+            displayName: this.displayName,
+            description: this.description,
+            author: this.author,
+            license: this.license,
+            apiConfig: this.apiConfig,
+            entities: this.entities,
+            scopes: this.scopes,
+            credentials: this.credentials,
+            endpoints: this.endpoints,
+            createdAt: this.createdAt,
+            updatedAt: this.updatedAt
+        };
+    }
+
+    /**
+     * Convert to JSON format (for api-module definition files)
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            version: this.version.value,
+            display: {
+                name: this.displayName,
+                description: this.description
+            },
+            api: {
+                baseUrl: this.apiConfig.baseUrl,
+                authType: this.apiConfig.authType,
+                version: this.apiConfig.version
+            },
+            entities: this.entities,
+            auth: {
+                type: this.apiConfig.authType,
+                scopes: this.scopes,
+                credentials: this.credentials
+            },
+            endpoints: this.endpoints
+        };
+    }
+
+    /**
+     * Generate display name from kebab-case name
+     */
+    _generateDisplayName() {
+        return this.name
+            .split('-')
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ');
+    }
+}
+
+module.exports = {ApiModule};