@friggframework/devtools 2.0.0-next.53 → 2.0.0-next.54

package/frigg-cli/__tests__/unit/utils/database-validator.test.js

@@ -113,6 +113,15 @@ describe('Database Validator Utility', () => {
             expect(result.error).toBeUndefined();
         });
 
+        it('should return documentdb when core returns documentdb', () => {
+            getDatabaseTypeFromCore.mockReturnValue('documentdb');
+
+            const result = getDatabaseType();
+
+            expect(result.dbType).toBe('documentdb');
+            expect(result.error).toBeUndefined();
+        });
+
         it('should return error when core throws error', () => {
             getDatabaseTypeFromCore.mockImplementation(() => {
                 throw new Error('[Frigg] Database not configured');
@@ -177,6 +186,17 @@ describe('Database Validator Utility', () => {
             expect(disconnectPrisma).toHaveBeenCalled();
         });
 
+        it('should connect successfully to DocumentDB and use $runCommandRaw', async () => {
+            const result = await testDatabaseConnection('mongodb://localhost', 'documentdb');
+
+            expect(result.connected).toBe(true);
+            expect(result.error).toBeUndefined();
+            expect(connectPrisma).toHaveBeenCalled();
+            expect(mockClient.$runCommandRaw).toHaveBeenCalledWith({ ping: 1 });
+            expect(mockClient.$queryRaw).not.toHaveBeenCalled(); // DocumentDB doesn't use SQL
+            expect(disconnectPrisma).toHaveBeenCalled();
+        });
+
         it('should connect successfully to PostgreSQL and use $queryRaw', async () => {
             const result = await testDatabaseConnection('postgresql://localhost', 'postgresql');
 
@@ -303,20 +323,32 @@ describe('Database Validator Utility', () => {
         // Note: Testing require.resolve behavior requires integration tests with real packages
         // These unit tests focus on error handling and package name selection
 
-        it('should use correct package name for MongoDB', () => {
-            // When MongoDB client doesn't exist, error message reveals the package name used
+        it('should check for MongoDB client directory', () => {
+            // When path doesn't exist, returns error about resolving module
             const result = checkPrismaClientGenerated('mongodb', '/nonexistent/path');
 
             expect(result.generated).toBe(false);
-            expect(result.error).toContain('@prisma-mongodb/client');
+            expect(result.error).toBeDefined();
+            expect(result.error).toContain('Failed to check Prisma client');
         });
 
-        it('should use correct package name for PostgreSQL', () => {
-            // When PostgreSQL client doesn't exist, error message reveals the package name used
+        it('should check for PostgreSQL client directory', () => {
+            // When path doesn't exist, returns error about resolving module
             const result = checkPrismaClientGenerated('postgresql', '/nonexistent/path');
 
             expect(result.generated).toBe(false);
-            expect(result.error).toContain('@prisma-postgresql/client');
+            expect(result.error).toBeDefined();
+            expect(result.error).toContain('Failed to check Prisma client');
+        });
+
+        it('should normalize DocumentDB to check MongoDB client directory', () => {
+            // DocumentDB should use the same client as MongoDB (prisma-mongodb directory)
+            // When path doesn't exist, returns error about resolving module
+            const result = checkPrismaClientGenerated('documentdb', '/nonexistent/path');
+
+            expect(result.generated).toBe(false);
+            expect(result.error).toBeDefined();
+            expect(result.error).toContain('Failed to check Prisma client');
         });
 
         it('should return error when MongoDB client not found', () => {
@@ -324,9 +356,8 @@ describe('Database Validator Utility', () => {
 
             expect(result.generated).toBe(false);
             expect(result.error).toBeDefined();
-            expect(result.error).toContain('not found');
-            expect(result.error).toContain('@prisma-mongodb/client');
-            expect(result.error).toContain('frigg db:setup');
+            // Error will be about resolving @friggframework/core module
+            expect(result.error).toContain('Failed to check Prisma client');
         });
 
         it('should return error when PostgreSQL client not found', () => {
@@ -334,15 +365,15 @@ describe('Database Validator Utility', () => {
 
             expect(result.generated).toBe(false);
             expect(result.error).toBeDefined();
-            expect(result.error).toContain('not found');
-            expect(result.error).toContain('@prisma-postgresql/client');
-            expect(result.error).toContain('frigg db:setup');
+            // Error will be about resolving @friggframework/core module
+            expect(result.error).toContain('Failed to check Prisma client');
         });
 
-        it('should provide helpful error message suggesting db:setup command', () => {
+        it('should return error when core package cannot be resolved', () => {
             const result = checkPrismaClientGenerated('mongodb', '/nonexistent/path');
 
-            expect(result.error).toContain('frigg db:setup');
+            expect(result.generated).toBe(false);
+            expect(result.error).toContain('Failed to check Prisma client');
         });
 
         it('should use process.cwd() by default when no project root specified', () => {

package/frigg-cli/__tests__/unit/utils/error-messages.test.js

@@ -16,6 +16,12 @@ describe('Error Messages Utility', () => {
             expect(DATABASE_URL_EXAMPLES.mongodb).toContain('replicaSet=rs0');
         });
 
+        it('should include DocumentDB connection string example', () => {
+            expect(DATABASE_URL_EXAMPLES.documentdb).toBeDefined();
+            expect(DATABASE_URL_EXAMPLES.documentdb).toContain('docdb');
+            expect(DATABASE_URL_EXAMPLES.documentdb).toContain('retryWrites=false');
+        });
+
         it('should include PostgreSQL connection string example', () => {
             expect(DATABASE_URL_EXAMPLES.postgresql).toBeDefined();
             expect(DATABASE_URL_EXAMPLES.postgresql).toContain('postgresql://');
@@ -31,10 +37,11 @@ describe('Error Messages Utility', () => {
             expect(typeof message).toBe('string');
         });
 
-        it('should include both database type examples', () => {
+        it('should include all database type examples', () => {
             const message = getDatabaseUrlMissingError();
 
             expect(message).toContain('MongoDB');
+            expect(message).toContain('DocumentDB');
             expect(message).toContain('PostgreSQL');
         });
 
@@ -42,6 +49,7 @@ describe('Error Messages Utility', () => {
             const message = getDatabaseUrlMissingError();
 
             expect(message).toContain(DATABASE_URL_EXAMPLES.mongodb);
+            expect(message).toContain(DATABASE_URL_EXAMPLES.documentdb);
             expect(message).toContain(DATABASE_URL_EXAMPLES.postgresql);
         });
 
@@ -119,6 +127,14 @@ describe('Error Messages Utility', () => {
             expect(message).toContain('27017');
         });
 
+        it('should include DocumentDB-specific troubleshooting for DocumentDB', () => {
+            const message = getDatabaseConnectionError(mockError, 'documentdb');
+
+            expect(message).toContain('DocumentDB');
+            expect(message).toContain('retryWrites=false');
+            expect(message).toContain('global-bundle.pem');
+        });
+
         it('should include PostgreSQL-specific troubleshooting for PostgreSQL', () => {
             const message = getDatabaseConnectionError(mockError, 'postgresql');
 
@@ -150,6 +166,12 @@ describe('Error Messages Utility', () => {
             expect(messagePostgres).toContain('Troubleshooting');
         });
 
+        it('should display database name in the error output', () => {
+            const message = getDatabaseConnectionError(mockError, 'documentdb');
+
+            expect(message).toContain('AWS DocumentDB (MongoDB-compatible)');
+        });
+
         it('should show DATABASE_URL when available', () => {
             process.env.DATABASE_URL = 'mongodb://test';
             const message = getDatabaseConnectionError(mockError, 'mongodb');
@@ -187,6 +209,13 @@ describe('Error Messages Utility', () => {
             expect(message).toContain('@prisma-mongodb/client');
         });
 
+        it('should mention Mongo client reuse for DocumentDB', () => {
+            const message = getPrismaClientNotGeneratedError('documentdb');
+
+            expect(message).toContain('@prisma-mongodb/client');
+            expect(message).toContain('DocumentDB reuses the MongoDB Prisma client');
+        });
+
         it('should include correct client package name for PostgreSQL', () => {
             const message = getPrismaClientNotGeneratedError('postgresql');
 
@@ -255,13 +284,19 @@ describe('Error Messages Utility', () => {
         it('should include database type for MongoDB', () => {
             const message = getDatabaseSetupSuccess('mongodb', 'development');
 
-            expect(message).toContain('mongodb');
+            expect(message).toContain('MongoDB');
         });
 
         it('should include database type for PostgreSQL', () => {
             const message = getDatabaseSetupSuccess('postgresql', 'production');
 
-            expect(message).toContain('postgresql');
+            expect(message).toContain('PostgreSQL');
+        });
+
+        it('should include database type for DocumentDB', () => {
+            const message = getDatabaseSetupSuccess('documentdb', 'production');
+
+            expect(message).toContain('AWS DocumentDB (MongoDB-compatible)');
         });
 
         it('should include stage information', () => {
@@ -280,6 +315,12 @@ describe('Error Messages Utility', () => {
             expect(postgresMessage).toContain('Migrations applied');
         });
 
+        it('should mention DocumentDB-specific schema messaging', () => {
+            const message = getDatabaseSetupSuccess('documentdb', 'development');
+
+            expect(message).toContain('Schema pushed to DocumentDB');
+        });
+
         it('should suggest next steps', () => {
             const message = getDatabaseSetupSuccess('mongodb', 'development');
 

package/frigg-cli/db-setup-command/index.js

@@ -4,22 +4,39 @@ const dotenv = require('dotenv');
 const {
     validateDatabaseUrl,
     getDatabaseType,
-    checkPrismaClientGenerated
+    checkPrismaClientGenerated,
 } = require('../utils/database-validator');
 const {
     runPrismaGenerate,
     checkDatabaseState,
     runPrismaMigrate,
     runPrismaDbPush,
-    getMigrationCommand
+    getMigrationCommand,
 } = require('@friggframework/core/database/utils/prisma-runner');
 const {
     getDatabaseUrlMissingError,
     getDatabaseTypeNotConfiguredError,
     getPrismaCommandError,
-    getDatabaseSetupSuccess
+    getDatabaseSetupSuccess,
 } = require('../utils/error-messages');
 
+function getDatabaseDisplayName(dbType) {
+    switch (dbType) {
+        case 'postgresql':
+            return 'PostgreSQL';
+        case 'mongodb':
+            return 'MongoDB';
+        case 'documentdb':
+            return 'AWS DocumentDB (MongoDB-compatible)';
+        default:
+            return dbType;
+    }
+}
+
+function getPrismaRunnerDbType(dbType) {
+    return dbType === 'documentdb' ? 'mongodb' : dbType;
+}
+
 /**
  * Database Setup Command
  * Sets up the database for a Frigg application:
@@ -75,10 +92,16 @@ async function dbSetupCommand(options = {}) {
         }
 
         const dbType = dbTypeResult.dbType;
-        console.log(chalk.cyan(`Database type: ${dbType}`));
+        const dbDisplayName = getDatabaseDisplayName(dbType);
+        const isPostgres = dbType === 'postgresql';
+        const isDocumentDb = dbType === 'documentdb';
+        const isMongoFamily = dbType === 'mongodb' || isDocumentDb;
+        const runnerDbType = getPrismaRunnerDbType(dbType);
+
+        console.log(chalk.cyan(`Database type: ${dbDisplayName}`));
 
         if (verbose) {
-            console.log(chalk.green(`✓ Using ${dbType}\n`));
+            console.log(chalk.green(`✓ Using ${dbDisplayName}\n`));
         }
 
         // Step 3: Check if Prisma client exists, generate if needed
@@ -91,22 +114,35 @@ async function dbSetupCommand(options = {}) {
 
         if (clientCheck.generated && !forceRegenerate) {
             // Client already exists and --force not specified
-            console.log(chalk.green('✓ Prisma client already exists (skipping generation)\n'));
+            console.log(
+                chalk.green(
+                    '✓ Prisma client already exists (skipping generation)\n'
+                )
+            );
             if (verbose) {
-                console.log(chalk.gray(`  Client location: ${clientCheck.path}\n`));
+                console.log(
+                    chalk.gray(`  Client location: ${clientCheck.path}\n`)
+                );
             }
         } else {
             // Client doesn't exist OR --force specified - generate it
             if (forceRegenerate && clientCheck.generated) {
-                console.log(chalk.yellow('⚠️  Forcing Prisma client regeneration...'));
+                console.log(
+                    chalk.yellow('⚠️  Forcing Prisma client regeneration...')
+                );
             } else {
                 console.log(chalk.cyan('Generating Prisma client...'));
             }
 
-            const generateResult = await runPrismaGenerate(dbType, verbose);
+            const generateResult = await runPrismaGenerate(
+                runnerDbType,
+                verbose
+            );
 
             if (!generateResult.success) {
-                console.error(getPrismaCommandError('generate', generateResult.error));
+                console.error(
+                    getPrismaCommandError('generate', generateResult.error)
+                );
                 if (generateResult.output) {
                     console.error(chalk.gray(generateResult.output));
                 }
@@ -124,25 +160,32 @@ async function dbSetupCommand(options = {}) {
             console.log(chalk.gray('Step 4: Checking database state...'));
         }
 
-        const stateCheck = await checkDatabaseState(dbType);
+        const stateCheck = await checkDatabaseState(runnerDbType);
 
         // Step 5: Run migrations or db push
-        if (dbType === 'postgresql') {
+        if (isPostgres) {
             console.log(chalk.cyan('Running database migrations...'));
 
             const migrationCommand = getMigrationCommand(stage);
 
             if (verbose) {
-                console.log(chalk.gray(`Using migration command: ${migrationCommand}`));
+                console.log(
+                    chalk.gray(`Using migration command: ${migrationCommand}`)
+                );
             }
 
             if (stateCheck.upToDate && migrationCommand === 'deploy') {
                 console.log(chalk.yellow('Database is already up-to-date'));
             } else {
-                const migrateResult = await runPrismaMigrate(migrationCommand, verbose);
+                const migrateResult = await runPrismaMigrate(
+                    migrationCommand,
+                    verbose
+                );
 
                 if (!migrateResult.success) {
-                    console.error(getPrismaCommandError('migrate', migrateResult.error));
+                    console.error(
+                        getPrismaCommandError('migrate', migrateResult.error)
+                    );
                     if (migrateResult.output) {
                         console.error(chalk.gray(migrateResult.output));
                     }
@@ -151,14 +194,19 @@ async function dbSetupCommand(options = {}) {
 
                 console.log(chalk.green('✓ Migrations applied\n'));
             }
+        } else if (isMongoFamily) {
+            const targetName = isDocumentDb
+                ? 'AWS DocumentDB (MongoDB-compatible)'
+                : 'MongoDB';
 
-        } else if (dbType === 'mongodb') {
-            console.log(chalk.cyan('Pushing schema to MongoDB...'));
+            console.log(chalk.cyan(`Pushing schema to ${targetName}...`));
 
             const pushResult = await runPrismaDbPush(verbose);
 
             if (!pushResult.success) {
-                console.error(getPrismaCommandError('db push', pushResult.error));
+                console.error(
+                    getPrismaCommandError('db push', pushResult.error)
+                );
                 if (pushResult.output) {
                     console.error(chalk.gray(pushResult.output));
                 }
@@ -170,7 +218,6 @@ async function dbSetupCommand(options = {}) {
 
         // Success!
         console.log(getDatabaseSetupSuccess(dbType, stage));
-
     } catch (error) {
         console.error(chalk.red('\n❌ Database setup failed'));
         console.error(chalk.gray(error.message));
@@ -182,9 +229,15 @@ async function dbSetupCommand(options = {}) {
 
         console.error(chalk.yellow('\nTroubleshooting:'));
         console.error(chalk.gray('  • Verify DATABASE_URL in your .env file'));
-        console.error(chalk.gray('  • Check database is running and accessible'));
-        console.error(chalk.gray('  • Ensure app definition has database configuration'));
-        console.error(chalk.gray('  • Run with --verbose flag for more details'));
+        console.error(
+            chalk.gray('  • Check database is running and accessible')
+        );
+        console.error(
+            chalk.gray('  • Ensure app definition has database configuration')
+        );
+        console.error(
+            chalk.gray('  • Run with --verbose flag for more details')
+        );
 
         process.exit(1);
     }

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

@@ -284,8 +284,10 @@ async function deployCommand(options) {
 
     console.log('\n✓ Deployment completed successfully!');
 
-    // Run post-deployment health check (unless --skip-doctor)
-    if (!options.skipDoctor) {
+    const skipHealthCheck = options.skipDoctor || appDefinition?.deployment?.skipPostDeploymentHealthCheck;
+
+    // Run post-deployment health check (unless disabled)
+    if (!skipHealthCheck) {
         const stackName = getStackName(appDefinition, options);
 
         if (stackName) {
@@ -295,7 +297,8 @@ async function deployCommand(options) {
             console.log('   Run "frigg doctor <stack-name>" manually to check stack health');
         }
     } else {
-        console.log('\n⏭️  Skipping post-deployment health check (--skip-doctor)');
+        const reason = options.skipDoctor ? '--skip-doctor flag' : 'deployment.skipPostDeploymentHealthCheck: true';
+        console.log(`\n⏭️  Skipping post-deployment health check (${reason})`);
     }
 }
 

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

@@ -8,6 +8,16 @@ const { connectPrisma, disconnectPrisma } = require('@friggframework/core/databa
  * Validates database configuration and connectivity for Frigg applications
  */
 
+/**
+ * Normalizes MongoDB-compatible database types to 'mongodb'
+ * DocumentDB uses the same Prisma client as MongoDB
+ * @param {'mongodb'|'postgresql'|'documentdb'} dbType - Database type
+ * @returns {'mongodb'|'postgresql'} Normalized database type
+ */
+function normalizeMongoCompatible(dbType) {
+    return dbType === 'documentdb' ? 'mongodb' : dbType;
+}
+
 /**
  * Validates that DATABASE_URL environment variable exists and has a value
  * @returns {Object} { valid: boolean, url?: string, error?: string }
@@ -62,7 +72,7 @@ function getDatabaseType() {
  * 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 {'mongodb'|'postgresql'|'documentdb'} dbType - Database type to determine appropriate health check
  * @param {number} timeout - Connection timeout in milliseconds (default: 5000)
  * @returns {Promise<Object>} { connected: boolean, error?: string }
  */
@@ -78,8 +88,8 @@ async function testDatabaseConnection(databaseUrl, dbType, timeout = 5000) {
         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') {
+        // MongoDB and DocumentDB don't support SQL, so we use the native ping command
+        if (dbType === 'mongodb' || dbType === 'documentdb') {
             // Use MongoDB's native ping command via $runCommandRaw
             await client.$runCommandRaw({ ping: 1 });
         } else {
@@ -109,12 +119,15 @@ async function testDatabaseConnection(databaseUrl, dbType, timeout = 5000) {
  * Checks if Prisma client is generated for the database type
  * Checks for the generated client directory in @friggframework/core/generated
  *
- * @param {'mongodb'|'postgresql'} dbType - Database type
+ * @param {'mongodb'|'postgresql'|'documentdb'} 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()) {
     try {
+        // Normalize DocumentDB to MongoDB (they use the same Prisma client)
+        const normalizedType = normalizeMongoCompatible(dbType);
+
         // Resolve where @friggframework/core actually is
         // This handles file: dependencies and symlinks correctly
         const corePackagePath = require.resolve('@friggframework/core', {
@@ -123,7 +136,7 @@ function checkPrismaClientGenerated(dbType, projectRoot = process.cwd()) {
         const corePackageDir = path.dirname(corePackagePath);
 
         // Check for the generated client directory (same path core uses)
-        const clientPath = path.join(corePackageDir, 'generated', `prisma-${dbType}`);
+        const clientPath = path.join(corePackageDir, 'generated', `prisma-${normalizedType}`);
         const clientIndexPath = path.join(clientPath, 'index.js');
 
         if (fs.existsSync(clientIndexPath)) {

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

@@ -6,13 +6,37 @@ const chalk = require('chalk');
  */
 
 /**
- * Database URL examples for both supported database types
+ * Normalizes MongoDB-compatible database types to 'mongodb'
+ * DocumentDB uses the same Prisma client as MongoDB
+ * @param {'mongodb'|'postgresql'|'documentdb'} dbType - Database type
+ * @returns {'mongodb'|'postgresql'} Normalized database type
+ */
+function normalizeMongoCompatible(dbType) {
+    return dbType === 'documentdb' ? 'mongodb' : dbType;
+}
+
+/**
+ * Database URL examples for supported database types
  */
 const DATABASE_URL_EXAMPLES = {
-    mongodb: 'mongodb://localhost:27017/frigg?replicaSet=rs0',
-    postgresql: 'postgresql://postgres:postgres@localhost:5432/frigg?schema=public'
+  mongodb: 'mongodb://localhost:27017/frigg?replicaSet=rs0',
+  documentdb: 'mongodb://frigg-user:yourPassword@docdb-cluster.cluster-xyz123.us-east-1.docdb.amazonaws.com:27017/frigg?tls=true&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false',
+  postgresql: 'postgresql://postgres:postgres@localhost:5432/frigg?schema=public'
 };
 
+function getDatabaseDisplayName(dbType) {
+  switch (dbType) {
+    case 'mongodb':
+      return 'MongoDB';
+    case 'documentdb':
+      return 'AWS DocumentDB (MongoDB-compatible)';
+    case 'postgresql':
+      return 'PostgreSQL';
+    default:
+      return dbType;
+  }
+}
+
 /**
  * Gets helpful error message for missing DATABASE_URL
  * @returns {string} Formatted error message
@@ -26,6 +50,9 @@ ${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 AWS DocumentDB (MongoDB-compatible):')}
+  ${chalk.gray('DATABASE_URL')}=${chalk.green(`"${DATABASE_URL_EXAMPLES.documentdb}"`)}
+
 ${chalk.cyan('For PostgreSQL:')}
   ${chalk.gray('DATABASE_URL')}=${chalk.green(`"${DATABASE_URL_EXAMPLES.postgresql}"`)}
 
@@ -73,19 +100,26 @@ const appDefinition = {
   }
 };
 `)}
+
+${chalk.gray('DocumentDB uses the MongoDB Prisma client. Make sure TLS is enabled and replica set compatibility is configured on your cluster.')}
 `;
 }
 
 /**
  * Gets helpful error message for database connection failure
  * @param {string} error - Connection error message
- * @param {'mongodb'|'postgresql'} dbType - Database type
+ * @param {'mongodb'|'postgresql'|'documentdb'} dbType - Database type
  * @returns {string} Formatted error message
  */
 function getDatabaseConnectionError(error, dbType) {
-    const troubleshootingSteps = dbType === 'mongodb'
-        ? getMongoDatabaseTroubleshooting()
-        : getPostgresTroubleshooting();
+    let troubleshootingSteps;
+    if (dbType === 'documentdb') {
+        troubleshootingSteps = getDocumentDbTroubleshooting();
+    } else if (dbType === 'mongodb') {
+        troubleshootingSteps = getMongoDatabaseTroubleshooting();
+    } else {
+        troubleshootingSteps = getPostgresTroubleshooting();
+    }
 
     return `
 ${chalk.red('❌ Failed to connect to database')}
@@ -93,6 +127,8 @@ ${chalk.red('❌ Failed to connect to database')}
 ${chalk.bold('Connection error:')}
 ${chalk.gray(error)}
 
+${chalk.bold('Database:')} ${chalk.cyan(getDatabaseDisplayName(dbType))}
+
 ${chalk.bold('Troubleshooting steps:')}
 ${troubleshootingSteps}
 
@@ -128,6 +164,26 @@ ${chalk.gray('5.')} Check network/firewall settings
 `;
 }
 
+function getDocumentDbTroubleshooting() {
+    return `
+${chalk.gray('1.')} Verify DocumentDB cluster is available
+   ${chalk.cyan('aws docdb describe-db-clusters --db-cluster-identifier <name>')}
+
+${chalk.gray('2.')} Use TLS with the AWS CA bundle
+   ${chalk.gray('Download: https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem')}
+   ${chalk.gray('Add ?tls=true&tlsCAFile=/path/to/global-bundle.pem to DATABASE_URL')}
+
+${chalk.gray('3.')} Disable retryable writes (DocumentDB limitation)
+   ${chalk.gray('Add retryWrites=false to DATABASE_URL query string')}
+
+${chalk.gray('4.')} Include replicaSet parameter
+   ${chalk.gray('DocumentDB requires replicaSet=rs0 even for single-node clusters')}
+
+${chalk.gray('5.')} Allow inbound access from your Lambda or local IP
+   ${chalk.gray('Update security groups / VPC rules for port 27017')}
+`;
+}
+
 /**
  * Gets PostgreSQL-specific troubleshooting steps
  * @returns {string} Formatted troubleshooting steps
@@ -157,11 +213,19 @@ ${chalk.gray('5.')} Verify network/firewall settings
 
 /**
  * Gets helpful error message for missing Prisma client
- * @param {'mongodb'|'postgresql'} dbType - Database type
+ * @param {'mongodb'|'postgresql'|'documentdb'} dbType - Database type
  * @returns {string} Formatted error message
  */
 function getPrismaClientNotGeneratedError(dbType) {
-    const clientName = `@prisma-${dbType}/client`;
+  // Normalize DocumentDB to MongoDB (they use the same Prisma client)
+  const normalizedType = normalizeMongoCompatible(dbType);
+  const clientName = `@prisma-${normalizedType}/client`;
+  const documentDbNote = dbType === 'documentdb'
+    ? [
+      chalk.gray('  • DocumentDB reuses the MongoDB Prisma client (prisma-mongodb)'),
+      chalk.gray('  • Confirm your connection string includes tls=true and retryWrites=false')
+    ].join('\n')
+    : '';
 
     return `
 ${chalk.red(`❌ Prisma client not generated for ${dbType}`)}
@@ -174,6 +238,7 @@ ${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)')}
+${documentDbNote ? `${documentDbNote}\n` : ''}
 `;
 }
 
@@ -205,23 +270,30 @@ ${chalk.cyan('  Review Prisma schema')} ${chalk.gray('(node_modules/@friggframew
 
 /**
  * Gets success message for database setup completion
- * @param {'mongodb'|'postgresql'} dbType - Database type
+ * @param {'mongodb'|'postgresql'|'documentdb'} dbType - Database type
  * @param {string} stage - Deployment stage
  * @returns {string} Formatted success message
  */
 function getDatabaseSetupSuccess(dbType, stage) {
+    const databaseDisplayName = getDatabaseDisplayName(dbType);
+    const schemaAction = dbType === 'postgresql'
+        ? 'Migrations applied'
+        : dbType === 'documentdb'
+            ? 'Schema pushed to DocumentDB'
+            : 'Schema pushed to database';
+
     return `
 ${chalk.green('✅ Database setup completed successfully!')}
 
 ${chalk.bold('Configuration:')}
-${chalk.gray('  Database type:')} ${chalk.cyan(dbType)}
+${chalk.gray('  Database type:')} ${chalk.cyan(databaseDisplayName)}
 ${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.gray('  ✓')} ${schemaAction}
 
 ${chalk.yellow('Next steps:')}
 ${chalk.cyan('  frigg start')} ${chalk.gray('(start your application)')}