@friggframework/devtools 2.0.0-next.40 → 2.0.0-next.42

package/frigg-cli/utils/database-validator.js

@@ -0,0 +1,158 @@
+const path = require('path');
+const fs = require('fs');
+const { getDatabaseType: getDatabaseTypeFromCore } = require('@friggframework/core/database/config');
+const { connectPrisma, disconnectPrisma } = require('@friggframework/core/database/prisma');
+
+/**
+ * Database Validation Utility
+ * Validates database configuration and connectivity for Frigg applications
+ */
+
+/**
+ * Validates that DATABASE_URL environment variable exists and has a value
+ * @returns {Object} { valid: boolean, url?: string, error?: string }
+ */
+function validateDatabaseUrl() {
+    const databaseUrl = process.env.DATABASE_URL;
+
+    if (!databaseUrl) {
+        return {
+            valid: false,
+            error: 'DATABASE_URL environment variable not found'
+        };
+    }
+
+    if (databaseUrl.trim() === '') {
+        return {
+            valid: false,
+            error: 'DATABASE_URL environment variable is empty'
+        };
+    }
+
+    return {
+        valid: true,
+        url: databaseUrl
+    };
+}
+
+/**
+ * Determines database type from backend app definition
+ * Reuses core logic from @friggframework/core/database/config
+ *
+ * @returns {Object} { dbType?: 'mongodb'|'postgresql', error?: string }
+ */
+function getDatabaseType() {
+    try {
+        // Use the core database config logic (same logic used at runtime)
+        const dbType = getDatabaseTypeFromCore();
+        return { dbType };
+    } catch (error) {
+        // Convert thrown errors to error object format for CLI
+        // Strip [Frigg] prefix from error messages for cleaner CLI output
+        const errorMessage = error.message.replace(/^\[Frigg\]\s*/, '');
+        return { error: errorMessage };
+    }
+}
+
+/**
+ * Tests database connectivity by attempting to connect
+ * Uses the same Prisma client configuration as runtime
+ *
+ * @param {string} databaseUrl - Database connection URL (for validation purposes)
+ * @param {'mongodb'|'postgresql'} dbType - Database type to determine appropriate health check
+ * @param {number} timeout - Connection timeout in milliseconds (default: 5000)
+ * @returns {Promise<Object>} { connected: boolean, error?: string }
+ */
+async function testDatabaseConnection(databaseUrl, dbType, timeout = 5000) {
+    try {
+        // Use the core Prisma client (same client used at runtime)
+        // This automatically uses the correct client based on DB_TYPE
+        const connectPromise = connectPrisma();
+        const timeoutPromise = new Promise((_, reject) =>
+            setTimeout(() => reject(new Error('Connection timeout')), timeout)
+        );
+
+        const client = await Promise.race([connectPromise, timeoutPromise]);
+
+        // Test with database-appropriate health check
+        // MongoDB doesn't support SQL, so we use the native ping command
+        if (dbType === 'mongodb') {
+            // Use MongoDB's native ping command via $runCommandRaw
+            await client.$runCommandRaw({ ping: 1 });
+        } else {
+            // PostgreSQL: use a simple SQL query
+            await client.$queryRaw`SELECT 1`;
+        }
+
+        await disconnectPrisma();
+
+        return { connected: true };
+
+    } catch (error) {
+        try {
+            await disconnectPrisma();
+        } catch (disconnectError) {
+            // Ignore disconnect errors
+        }
+
+        return {
+            connected: false,
+            error: error.message
+        };
+    }
+}
+
+/**
+ * Checks if Prisma client is generated for the database type
+ * Uses require.resolve to find the client in node_modules
+ *
+ * @param {'mongodb'|'postgresql'} dbType - Database type
+ * @param {string} projectRoot - Project root directory (used for require.resolve context)
+ * @returns {Object} { generated: boolean, path?: string, error?: string }
+ */
+function checkPrismaClientGenerated(dbType, projectRoot = process.cwd()) {
+    const clientPackageName = `@prisma-${dbType}/client`;
+
+    try {
+        // First, resolve where @friggframework/core actually is
+        // This handles file: dependencies and symlinks correctly
+        const corePackagePath = require.resolve('@friggframework/core', {
+            paths: [projectRoot]
+        });
+        const corePackageDir = path.dirname(corePackagePath);
+
+        // Now look for the Prisma client within the resolved core package
+        const clientPath = require.resolve(clientPackageName, {
+            paths: [
+                corePackageDir,  // Look in the actual core package location
+                projectRoot      // Fallback to project root
+            ]
+        });
+
+        return {
+            generated: true,
+            path: path.dirname(clientPath)
+        };
+
+    } catch (error) {
+        // require.resolve throws MODULE_NOT_FOUND if the client doesn't exist
+        if (error.code === 'MODULE_NOT_FOUND') {
+            return {
+                generated: false,
+                error: `Prisma client for ${dbType} (${clientPackageName}) not found. Run 'frigg db:setup' to generate it.`
+            };
+        }
+
+        return {
+            generated: false,
+            error: `Failed to check Prisma client: ${error.message}`
+        };
+    }
+}
+
+module.exports = {
+    validateDatabaseUrl,
+    getDatabaseType,
+    testDatabaseConnection,
+    checkPrismaClientGenerated
+};

package/frigg-cli/utils/error-messages.js

@@ -0,0 +1,257 @@
+const chalk = require('chalk');
+
+/**
+ * Error Messages Module
+ * Provides helpful, context-aware error messages for database setup issues
+ */
+
+/**
+ * Database URL examples for both supported database types
+ */
+const DATABASE_URL_EXAMPLES = {
+    mongodb: 'mongodb://localhost:27017/frigg?replicaSet=rs0',
+    postgresql: 'postgresql://postgres:postgres@localhost:5432/frigg?schema=public'
+};
+
+/**
+ * Gets helpful error message for missing DATABASE_URL
+ * @returns {string} Formatted error message
+ */
+function getDatabaseUrlMissingError() {
+    return `
+${chalk.red('❌ DATABASE_URL environment variable not found')}
+
+${chalk.bold('Add DATABASE_URL to your .env file:')}
+
+${chalk.cyan('For MongoDB:')}
+  ${chalk.gray('DATABASE_URL')}=${chalk.green(`"${DATABASE_URL_EXAMPLES.mongodb}"`)}
+
+${chalk.cyan('For PostgreSQL:')}
+  ${chalk.gray('DATABASE_URL')}=${chalk.green(`"${DATABASE_URL_EXAMPLES.postgresql}"`)}
+
+${chalk.yellow('Then run:')} ${chalk.cyan('frigg db:setup')}
+`;
+}
+
+/**
+ * Gets helpful error message for missing database type configuration
+ * @returns {string} Formatted error message
+ */
+function getDatabaseTypeNotConfiguredError() {
+    return `
+${chalk.red('❌ Database type not configured in app definition')}
+
+${chalk.bold('Add database configuration to your app definition file:')}
+${chalk.gray('(backend/index.js or index.js)')}
+
+${chalk.cyan('For PostgreSQL:')}
+${chalk.gray(`
+const appDefinition = {
+  // ... other configuration
+  database: {
+    postgres: { enable: true }
+  }
+};
+`)}
+
+${chalk.cyan('For MongoDB:')}
+${chalk.gray(`
+const appDefinition = {
+  // ... other configuration
+  database: {
+    mongoDB: { enable: true }
+  }
+};
+`)}
+
+${chalk.cyan('For AWS DocumentDB (MongoDB-compatible):')}
+${chalk.gray(`
+const appDefinition = {
+  // ... other configuration
+  database: {
+    documentDB: { enable: true }
+  }
+};
+`)}
+`;
+}
+
+/**
+ * Gets helpful error message for database connection failure
+ * @param {string} error - Connection error message
+ * @param {'mongodb'|'postgresql'} dbType - Database type
+ * @returns {string} Formatted error message
+ */
+function getDatabaseConnectionError(error, dbType) {
+    const troubleshootingSteps = dbType === 'mongodb'
+        ? getMongoDatabaseTroubleshooting()
+        : getPostgresTroubleshooting();
+
+    return `
+${chalk.red('❌ Failed to connect to database')}
+
+${chalk.bold('Connection error:')}
+${chalk.gray(error)}
+
+${chalk.bold('Troubleshooting steps:')}
+${troubleshootingSteps}
+
+${chalk.yellow('Verify your DATABASE_URL:')} ${chalk.cyan(process.env.DATABASE_URL || 'not set')}
+`;
+}
+
+/**
+ * Gets MongoDB-specific troubleshooting steps
+ * @returns {string} Formatted troubleshooting steps
+ */
+function getMongoDatabaseTroubleshooting() {
+    return `
+${chalk.gray('1.')} Verify MongoDB is running
+   ${chalk.cyan('docker ps')} ${chalk.gray('(if using Docker)')}
+   ${chalk.cyan('mongosh --eval "db.version()"')} ${chalk.gray('(test connection)')}
+
+${chalk.gray('2.')} Check if replica set is initialized
+   ${chalk.gray('MongoDB requires a replica set for Prisma')}
+   ${chalk.cyan('mongosh')}
+   ${chalk.cyan('rs.status()')} ${chalk.gray('(should show replica set info)')}
+
+${chalk.gray('3.')} Initialize replica set if needed
+   ${chalk.cyan('docker exec -it <mongodb-container> mongosh')}
+   ${chalk.cyan('rs.initiate()')}
+
+${chalk.gray('4.')} Verify connection string format
+   ${chalk.gray('mongodb://[username:password@]host[:port]/database[?options]')}
+   ${chalk.green('Example: mongodb://localhost:27017/frigg?replicaSet=rs0')}
+
+${chalk.gray('5.')} Check network/firewall settings
+   ${chalk.gray('Ensure port 27017 (default) is accessible')}
+`;
+}
+
+/**
+ * Gets PostgreSQL-specific troubleshooting steps
+ * @returns {string} Formatted troubleshooting steps
+ */
+function getPostgresTroubleshooting() {
+    return `
+${chalk.gray('1.')} Verify PostgreSQL is running
+   ${chalk.cyan('docker ps')} ${chalk.gray('(if using Docker)')}
+   ${chalk.cyan('pg_isready')} ${chalk.gray('(test if server is ready)')}
+
+${chalk.gray('2.')} Check connection string format
+   ${chalk.gray('postgresql://[username:password@]host[:port]/database[?options]')}
+   ${chalk.green('Example: postgresql://postgres:postgres@localhost:5432/frigg?schema=public')}
+
+${chalk.gray('3.')} Verify database exists
+   ${chalk.cyan('psql -U postgres -l')} ${chalk.gray('(list databases)')}
+   ${chalk.cyan('CREATE DATABASE frigg;')} ${chalk.gray('(if needed)')}
+
+${chalk.gray('4.')} Check pg_hba.conf allows connections
+   ${chalk.gray('Location: /var/lib/postgresql/data/pg_hba.conf (Docker)')}
+   ${chalk.gray('Ensure trust/md5 authentication is enabled for your host')}
+
+${chalk.gray('5.')} Verify network/firewall settings
+   ${chalk.gray('Ensure port 5432 (default) is accessible')}
+`;
+}
+
+/**
+ * Gets helpful error message for missing Prisma client
+ * @param {'mongodb'|'postgresql'} dbType - Database type
+ * @returns {string} Formatted error message
+ */
+function getPrismaClientNotGeneratedError(dbType) {
+    const clientName = `@prisma-${dbType}/client`;
+
+    return `
+${chalk.red(`❌ Prisma client not generated for ${dbType}`)}
+
+${chalk.bold('The Prisma client needs to be generated before starting the application.')}
+
+${chalk.yellow('Run:')} ${chalk.cyan('frigg db:setup')}
+
+${chalk.gray('This will:')}
+${chalk.gray('  • Generate the Prisma client')} ${chalk.gray(`(${clientName})`)}
+${chalk.gray('  • Set up database schema')}
+${chalk.gray('  • Run migrations (PostgreSQL) or db push (MongoDB)')}
+`;
+}
+
+/**
+ * Gets helpful error message for Prisma command failures
+ * @param {string} command - Command that failed (generate, migrate, push)
+ * @param {string} error - Error message
+ * @returns {string} Formatted error message
+ */
+function getPrismaCommandError(command, error) {
+    return `
+${chalk.red(`❌ Prisma ${command} failed`)}
+
+${chalk.bold('Error:')}
+${chalk.gray(error)}
+
+${chalk.bold('Common causes:')}
+${chalk.gray('  • Database schema has conflicts')}
+${chalk.gray('  • Database connection lost during operation')}
+${chalk.gray('  • Insufficient permissions')}
+${chalk.gray('  • Schema file is invalid')}
+
+${chalk.yellow('Try:')}
+${chalk.cyan('  frigg db:setup')} ${chalk.gray('(re-run setup)')}
+${chalk.cyan('  Check your DATABASE_URL')} ${chalk.gray('(verify connection string)')}
+${chalk.cyan('  Review Prisma schema')} ${chalk.gray('(node_modules/@friggframework/core/prisma-*/schema.prisma)')}
+`;
+}
+
+/**
+ * Gets success message for database setup completion
+ * @param {'mongodb'|'postgresql'} dbType - Database type
+ * @param {string} stage - Deployment stage
+ * @returns {string} Formatted success message
+ */
+function getDatabaseSetupSuccess(dbType, stage) {
+    return `
+${chalk.green('✅ Database setup completed successfully!')}
+
+${chalk.bold('Configuration:')}
+${chalk.gray('  Database type:')} ${chalk.cyan(dbType)}
+${chalk.gray('  Stage:')} ${chalk.cyan(stage)}
+${chalk.gray('  Connection:')} ${chalk.green('verified')}
+
+${chalk.bold('What happened:')}
+${chalk.gray('  ✓')} Prisma client generated
+${chalk.gray('  ✓')} Database connection verified
+${chalk.gray('  ✓')} ${dbType === 'postgresql' ? 'Migrations applied' : 'Schema pushed to database'}
+
+${chalk.yellow('Next steps:')}
+${chalk.cyan('  frigg start')} ${chalk.gray('(start your application)')}
+`;
+}
+
+/**
+ * Gets warning message for database already up-to-date
+ * @returns {string} Formatted warning message
+ */
+function getDatabaseAlreadyUpToDate() {
+    return `
+${chalk.yellow('⚠️  Database is already up-to-date')}
+
+${chalk.gray('No migrations or schema changes detected.')}
+
+${chalk.yellow('If you expected changes:')}
+${chalk.gray('  • Check if schema was modified in node_modules/@friggframework/core/prisma-*/')}
+${chalk.gray('  • Verify DATABASE_URL points to the correct database')}
+${chalk.gray('  • Check if you\'re in the correct project directory')}
+`;
+}
+
+module.exports = {
+    DATABASE_URL_EXAMPLES,
+    getDatabaseUrlMissingError,
+    getDatabaseTypeNotConfiguredError,
+    getDatabaseConnectionError,
+    getPrismaClientNotGeneratedError,
+    getPrismaCommandError,
+    getDatabaseSetupSuccess,
+    getDatabaseAlreadyUpToDate
+};

package/frigg-cli/utils/prisma-runner.js

@@ -0,0 +1,280 @@
+const { execSync, spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const chalk = require('chalk');
+
+/**
+ * Prisma Command Runner Utility
+ * Handles execution of Prisma CLI commands for database setup
+ */
+
+/**
+ * Gets the path to the Prisma schema file for the database type
+ * @param {'mongodb'|'postgresql'} dbType - Database type
+ * @param {string} projectRoot - Project root directory
+ * @returns {string} Absolute path to schema file
+ * @throws {Error} If schema file doesn't exist
+ */
+function getPrismaSchemaPath(dbType, projectRoot = process.cwd()) {
+    // Try multiple locations for the schema file
+    // Priority order:
+    // 1. Local node_modules (where @friggframework/core is installed - production scenario)
+    // 2. Parent node_modules (workspace/monorepo setup)
+    const possiblePaths = [
+        // Check where Frigg is installed via npm (production scenario)
+        path.join(projectRoot, 'node_modules', '@friggframework', 'core', `prisma-${dbType}`, 'schema.prisma'),
+        path.join(projectRoot, '..', 'node_modules', '@friggframework', 'core', `prisma-${dbType}`, 'schema.prisma')
+    ];
+
+    for (const schemaPath of possiblePaths) {
+        if (fs.existsSync(schemaPath)) {
+            return schemaPath;
+        }
+    }
+
+    // If not found in any location, throw error
+    throw new Error(
+        `Prisma schema not found at:\n${possiblePaths.join('\n')}\n\n` +
+        'Ensure @friggframework/core is installed.'
+    );
+}
+
+/**
+ * Runs prisma generate for the specified database type
+ * @param {'mongodb'|'postgresql'} dbType - Database type
+ * @param {boolean} verbose - Enable verbose output
+ * @returns {Promise<Object>} { success: boolean, output?: string, error?: string }
+ */
+async function runPrismaGenerate(dbType, verbose = false) {
+    try {
+        const schemaPath = getPrismaSchemaPath(dbType);
+
+        if (verbose) {
+            console.log(chalk.gray(`Running: npx prisma generate --schema=${schemaPath}`));
+        }
+
+        const output = execSync(
+            `npx prisma generate --schema=${schemaPath}`,
+            {
+                encoding: 'utf8',
+                stdio: verbose ? 'inherit' : 'pipe',
+                env: {
+                    ...process.env,
+                    // Suppress Prisma telemetry prompts
+                    PRISMA_HIDE_UPDATE_MESSAGE: '1'
+                }
+            }
+        );
+
+        return {
+            success: true,
+            output: verbose ? 'Generated successfully' : output
+        };
+
+    } catch (error) {
+        return {
+            success: false,
+            error: error.message,
+            output: error.stdout?.toString() || error.stderr?.toString()
+        };
+    }
+}
+
+/**
+ * Checks database migration status
+ * @param {'mongodb'|'postgresql'} dbType - Database type
+ * @returns {Promise<Object>} { upToDate: boolean, pendingMigrations?: number, error?: string }
+ */
+async function checkDatabaseState(dbType) {
+    try {
+        // Only applicable for PostgreSQL (MongoDB uses db push)
+        if (dbType !== 'postgresql') {
+            return { upToDate: true };
+        }
+
+        const schemaPath = getPrismaSchemaPath(dbType);
+
+        const output = execSync(
+            `npx prisma migrate status --schema=${schemaPath}`,
+            {
+                encoding: 'utf8',
+                stdio: 'pipe',
+                env: {
+                    ...process.env,
+                    PRISMA_HIDE_UPDATE_MESSAGE: '1'
+                }
+            }
+        );
+
+        if (output.includes('Database schema is up to date')) {
+            return { upToDate: true };
+        }
+
+        // Parse pending migrations count
+        const pendingMatch = output.match(/(\d+) migration/);
+        const pendingMigrations = pendingMatch ? parseInt(pendingMatch[1]) : 0;
+
+        return {
+            upToDate: false,
+            pendingMigrations
+        };
+
+    } catch (error) {
+        // If migrate status fails, database might not be initialized
+        return {
+            upToDate: false,
+            error: error.message
+        };
+    }
+}
+
+/**
+ * Runs Prisma migrate for PostgreSQL
+ * @param {'dev'|'deploy'} command - Migration command (dev or deploy)
+ * @param {boolean} verbose - Enable verbose output
+ * @returns {Promise<Object>} { success: boolean, output?: string, error?: string }
+ */
+async function runPrismaMigrate(command = 'dev', verbose = false) {
+    return new Promise((resolve) => {
+        try {
+            const schemaPath = getPrismaSchemaPath('postgresql');
+
+            const args = [
+                'prisma',
+                'migrate',
+                command,
+                '--schema',
+                schemaPath
+            ];
+
+            if (verbose) {
+                console.log(chalk.gray(`Running: npx ${args.join(' ')}`));
+            }
+
+            const proc = spawn('npx', args, {
+                stdio: 'inherit',
+                env: {
+                    ...process.env,
+                    PRISMA_HIDE_UPDATE_MESSAGE: '1'
+                }
+            });
+
+            proc.on('error', (error) => {
+                resolve({
+                    success: false,
+                    error: error.message
+                });
+            });
+
+            proc.on('close', (code) => {
+                if (code === 0) {
+                    resolve({
+                        success: true,
+                        output: 'Migration completed successfully'
+                    });
+                } else {
+                    resolve({
+                        success: false,
+                        error: `Migration process exited with code ${code}`
+                    });
+                }
+            });
+
+        } catch (error) {
+            resolve({
+                success: false,
+                error: error.message
+            });
+        }
+    });
+}
+
+/**
+ * Runs Prisma db push for MongoDB
+ * Interactive - will prompt user if data loss detected
+ * @param {boolean} verbose - Enable verbose output
+ * @returns {Promise<Object>} { success: boolean, output?: string, error?: string }
+ */
+async function runPrismaDbPush(verbose = false) {
+    return new Promise((resolve) => {
+        try {
+            const schemaPath = getPrismaSchemaPath('mongodb');
+
+            const args = [
+                'prisma',
+                'db',
+                'push',
+                '--schema',
+                schemaPath,
+                '--skip-generate' // We generate separately
+            ];
+
+            if (verbose) {
+                console.log(chalk.gray(`Running: npx ${args.join(' ')}`));
+            }
+
+            console.log(chalk.yellow('⚠️  Interactive mode: You may be prompted if schema changes cause data loss'));
+
+            const proc = spawn('npx', args, {
+                stdio: 'inherit', // Interactive mode - user can respond to prompts
+                env: {
+                    ...process.env,
+                    PRISMA_HIDE_UPDATE_MESSAGE: '1'
+                }
+            });
+
+            proc.on('error', (error) => {
+                resolve({
+                    success: false,
+                    error: error.message
+                });
+            });
+
+            proc.on('close', (code) => {
+                if (code === 0) {
+                    resolve({
+                        success: true,
+                        output: 'Database push completed successfully'
+                    });
+                } else {
+                    resolve({
+                        success: false,
+                        error: `Database push process exited with code ${code}`
+                    });
+                }
+            });
+
+        } catch (error) {
+            resolve({
+                success: false,
+                error: error.message
+            });
+        }
+    });
+}
+
+/**
+ * Determines migration command based on STAGE environment variable
+ * @param {string} stage - Stage from CLI option or environment
+ * @returns {'dev'|'deploy'}
+ */
+function getMigrationCommand(stage) {
+    const normalizedStage = (stage || process.env.STAGE || 'development').toLowerCase();
+
+    const developmentStages = ['dev', 'local', 'test', 'development'];
+
+    if (developmentStages.includes(normalizedStage)) {
+        return 'dev';
+    }
+
+    return 'deploy';
+}
+
+module.exports = {
+    getPrismaSchemaPath,
+    runPrismaGenerate,
+    checkDatabaseState,
+    runPrismaMigrate,
+    runPrismaDbPush,
+    getMigrationCommand
+};