@gokiteam/goki-dev 0.2.0

package/cli/ProjectCLI.js

@@ -0,0 +1,2322 @@
+import fs from 'fs'
+import path from 'path'
+import { execa } from 'execa'
+import { Logger } from './Logger.js'
+import { DevToolsChecker } from './DevToolsChecker.js'
+import { DevToolsManager } from './DevToolsManager.js'
+import { DockerManager } from './DockerManager.js'
+import { DatabaseManager } from './DatabaseManager.js'
+import { PubSubManager } from './PubSubManager.js'
+import { NgrokManager } from './NgrokManager.js'
+import { computeProxyRewrites } from './HttpProxyRewriter.js'
+import { computeWebhookRewrites } from './WebhookUrlRewriter.js'
+import { generateComposeOverride, getOverridePath } from './ComposeOverrideGenerator.js'
+import { ensureMcpConfig, checkClaudePermissions, addClaudePermissions } from './McpConfigManager.js'
+import { ConfigManager } from './ConfigManager.js'
+import { formatStartupOutput } from './UiFormatter.js'
+import { SnapshotManager } from './SnapshotManager.js'
+import { FunctionManager } from './FunctionManager.js'
+
+export class ProjectCLI {
+  constructor (config) {
+    this.config = config
+    this.validateConfig()
+  }
+
+  validateConfig () {
+    // Only name is truly required
+    // database/schemaPath are only needed for PostgreSQL projects
+    const required = ['name']
+    for (const field of required) {
+      if (!this.config[field]) {
+        throw new Error(`Missing required config field: ${field}`)
+      }
+    }
+    // Warn if docker.composeFile is missing, default to docker-compose.yaml
+    if (!this.config.docker?.composeFile) {
+      Logger.warn('Warning: docker.composeFile not specified, defaulting to docker-compose.yaml')
+    }
+    // Validate that if database is specified, schemaPath should also be specified
+    if (this.config.database && !this.config.schemaPath) {
+      Logger.warn('Warning: database specified but schemaPath is missing')
+    }
+    // Validate services configuration matches project needs
+    this.validateServicesConfig()
+    this.validateHttpProxyConfig()
+  }
+
+  validateServicesConfig () {
+    const services = this.config.services || {}
+    // If project uses PostgreSQL (has database config), postgres service should be enabled
+    if (this.config.database && services.postgres !== true) {
+      Logger.error(`Error: Project uses PostgreSQL (database: ${this.config.database}) but postgres service is not enabled`)
+      Logger.error('Add to your .dev-tools/config.js:')
+      Logger.error('  services: { postgres: true }')
+      process.exit(1)
+    }
+    // If project has pubsub topics, pubsub should be enabled (it's on by default)
+    if (this.config.pubsub?.topics?.length && services.pubsub === false) {
+      Logger.warn('Warning: Project has Pub/Sub topics but pubsub service is disabled')
+    }
+    // Kibana requires Elasticsearch
+    if (services.kibana === true && services.elasticsearch !== true) {
+      Logger.warn('Warning: Kibana is enabled but Elasticsearch is not. Kibana requires Elasticsearch.')
+    }
+  }
+
+  validateHttpProxyConfig () {
+    const httpProxy = this.config.httpProxy
+    if (!httpProxy?.enabled) return
+    const hasInclude = Array.isArray(httpProxy.include) && httpProxy.include.length > 0
+    const hasExclude = Array.isArray(httpProxy.exclude) && httpProxy.exclude.length > 0
+    if (hasInclude && hasExclude) {
+      Logger.warn('Warning: httpProxy has both include and exclude — include takes priority, exclude is ignored')
+    }
+    if (hasInclude) {
+      for (const pattern of httpProxy.include) {
+        if (typeof pattern !== 'string' || pattern.length === 0) {
+          throw new Error('httpProxy.include must contain non-empty strings')
+        }
+      }
+    }
+    if (hasExclude) {
+      for (const pattern of httpProxy.exclude) {
+        if (typeof pattern !== 'string' || pattern.length === 0) {
+          throw new Error('httpProxy.exclude must contain non-empty strings')
+        }
+      }
+    }
+  }
+
+  getBaseCompose () {
+    return this.config.docker?.composeFile || 'docker-compose.yaml'
+  }
+
+  getOverrideCompose () {
+    return getOverridePath(process.cwd())
+  }
+
+  getContainerName () {
+    return this.config.docker?.containerName || null
+  }
+
+  getAppPort () {
+    return this.config.docker?.ports?.http || null
+  }
+
+  getServiceDescription (serviceName) {
+    // For backward compatibility (used in other places)
+    return this.config.serviceDescriptions?.[serviceName] || this.getDefaultServiceDescription(serviceName)
+  }
+
+  async promptStartDocker () {
+    console.log('\n🐳 Docker is not running.\n')
+    const inquirer = await import('inquirer')
+    const { startDocker } = await inquirer.default.prompt([{
+      type: 'confirm',
+      name: 'startDocker',
+      message: 'Start Docker Desktop now?',
+      default: true
+    }])
+    return startDocker
+  }
+
+  async promptMcpPermissions () {
+    const savedPreference = ConfigManager.getMcpPreference()
+    const { allowed: claudeSettingsExist } = checkClaudePermissions()
+    // Case 1: User previously answered
+    if (savedPreference !== null) {
+      if (savedPreference.allowed === true) {
+        // User said "yes" previously
+        if (claudeSettingsExist) {
+          // Settings exist - all good, skip prompt
+          return
+        }
+        // Settings missing - re-enable without prompting
+        console.log('')
+        console.log('  ⚠️  MCP permissions were previously enabled but settings are missing')
+        console.log('     Re-enabling...\n')
+        addClaudePermissions()
+        console.log('  ✓ Re-enabled .claude/settings.local.json\n')
+        return
+      } else {
+        // User said "no" previously - respect their choice, never ask again
+        return
+      }
+    }
+    // Case 2: No saved preference but Claude settings manually added
+    if (claudeSettingsExist) {
+      // Save preference so we don't ask again
+      ConfigManager.saveMcpPreference(true)
+      return
+    }
+    // Case 3: First time - prompt user
+    console.log('')
+    console.log('  🤖 Claude Code MCP permissions')
+    console.log('     Allow Claude Code to use dev-tools MCP commands without prompting?')
+    console.log('     This adds "mcp__goki-dev-tools__*" to .claude/settings.local.json\n')
+    const inquirer = await import('inquirer')
+    const { allow } = await inquirer.default.prompt([{
+      type: 'confirm',
+      name: 'allow',
+      message: 'Allow all dev-tools MCP tools for Claude Code?',
+      default: true
+    }])
+    // Save preference (whether yes or no)
+    ConfigManager.saveMcpPreference(allow)
+    // If allowed, update Claude settings
+    if (allow) {
+      const result = addClaudePermissions()
+      const action = result.created ? 'Created' : 'Updated'
+      console.log(`  ✓ ${action} .claude/settings.local.json\n`)
+    }
+  }
+
+  detectPackageManager () {
+    const projectDir = process.cwd()
+    if (fs.existsSync(path.join(projectDir, 'yarn.lock'))) {
+      return { type: 'yarn', command: 'yarn', args: ['install'] }
+    }
+    if (fs.existsSync(path.join(projectDir, 'pnpm-lock.yaml'))) {
+      return { type: 'pnpm', command: 'pnpm', args: ['install'] }
+    }
+    if (fs.existsSync(path.join(projectDir, 'package-lock.json'))) {
+      return { type: 'npm', command: 'npm', args: ['install'] }
+    }
+    return { type: 'npm', command: 'npm', args: ['install'] }
+  }
+
+  areDependenciesInstalled () {
+    const projectDir = process.cwd()
+    const nodeModulesPath = path.join(projectDir, 'node_modules')
+    const yarnPath = path.join(projectDir, '.yarn')
+    const pnpCjsPath = path.join(projectDir, '.pnp.cjs')
+    if (fs.existsSync(nodeModulesPath)) {
+      return true
+    }
+    if (fs.existsSync(yarnPath) || fs.existsSync(pnpCjsPath)) {
+      return true
+    }
+    return false
+  }
+
+  async ensureDependencies () {
+    const projectDir = process.cwd()
+    const packageJsonPath = path.join(projectDir, 'package.json')
+    if (!fs.existsSync(packageJsonPath)) {
+      return
+    }
+    if (this.areDependenciesInstalled()) {
+      return
+    }
+    const pm = this.detectPackageManager()
+    const spinner = Logger.spinner(`Installing dependencies with ${pm.type}...`)
+    try {
+      await execa(pm.command, pm.args, {
+        cwd: projectDir,
+        stdio: 'pipe'
+      })
+      spinner.succeed('Dependencies installed!')
+    } catch (error) {
+      spinner.fail('Failed to install dependencies')
+      Logger.error(error.message)
+      Logger.info('\nTry running manually:')
+      Logger.info(`  ${pm.command} ${pm.args.join(' ')}`)
+      process.exit(1)
+    }
+  }
+
+  async startDockerWithPrompt () {
+    const spinner = Logger.spinner('Starting Docker Desktop')
+    try {
+      await DockerManager.startDockerDesktop()
+      spinner.text = 'Waiting for Docker to be ready (this may take 10-30 seconds)...'
+      await DockerManager.waitForDockerReady()
+      spinner.succeed('Docker Desktop started!')
+    } catch (error) {
+      spinner.fail('Failed to start Docker')
+      Logger.error(error.message)
+      process.exit(1)
+    }
+  }
+
+  async checkServiceStatus (serviceName, port) {
+    try {
+      const response = await fetch(`http://localhost:${port}`, {
+        method: 'GET',
+        signal: AbortSignal.timeout(1000)
+      })
+      return response.ok || response.status < 500 ? '✓ running' : '○ stopped'
+    } catch {
+      return '○ stopped'
+    }
+  }
+
+  async promptStartDevTools () {
+    const services = this.config.services || {}
+    const enabledServices = DevToolsManager.getEnabledServices(services)
+    console.log('\n📦 Dev-tools is not running.\n')
+    console.log('This project requires the following services:\n')
+    // Service port mapping
+    const ports = {
+      redis: 6379,
+      pubsub: 8085,
+      postgres: 5432,
+      firestore: 8080,
+      'redis-logs': 6380,
+      elasticsearch: 9200,
+      kibana: 5601
+    }
+    // Check status of each service
+    const serviceData = await Promise.all(enabledServices.map(async (name) => {
+      const port = ports[name] || '-'
+      const desc = this.config.serviceDescriptions?.[name] || this.getDefaultServiceDescription(name)
+      const status = await this.checkServiceStatus(name, port)
+      return { name, desc, port, status }
+    }))
+    // Calculate column widths
+    const nameWidth = Math.max(10, ...serviceData.map(s => s.name.length)) + 2
+    const descWidth = Math.max(20, ...serviceData.map(s => s.desc.length)) + 2
+    const portWidth = 8
+    const statusWidth = 12
+    // Print table header
+    const header = `  ${'Service'.padEnd(nameWidth)}${'Description'.padEnd(descWidth)}${'Port'.padEnd(portWidth)}${'Status'.padEnd(statusWidth)}`
+    const separator = `  ${'-'.repeat(nameWidth)}${'-'.repeat(descWidth)}${'-'.repeat(portWidth)}${'-'.repeat(statusWidth)}`
+    console.log(header)
+    console.log(separator)
+    // Print table rows
+    for (const svc of serviceData) {
+      const statusColor = svc.status.startsWith('✓') ? '\x1b[32m' : '\x1b[90m' // green for running, gray for stopped
+      const reset = '\x1b[0m'
+      console.log(`  ${svc.name.padEnd(nameWidth)}${svc.desc.padEnd(descWidth)}${String(svc.port).padEnd(portWidth)}${statusColor}${svc.status}${reset}`)
+    }
+    console.log('')
+    const inquirer = await import('inquirer')
+    const { startDevTools } = await inquirer.default.prompt([{
+      type: 'confirm',
+      name: 'startDevTools',
+      message: 'Start dev-tools now?',
+      default: true
+    }])
+    return startDevTools
+  }
+
+  getDefaultServiceDescription (serviceName) {
+    const defaults = {
+      redis: 'cache & locks',
+      pubsub: 'GCP Pub/Sub emulator',
+      postgres: 'PostgreSQL database',
+      firestore: 'GCP Firestore emulator',
+      'redis-logs': 'log storage LRU',
+      elasticsearch: 'search engine ~2GB',
+      kibana: 'Elasticsearch dashboard'
+    }
+    return defaults[serviceName] || ''
+  }
+
+  async startDevToolsWithServices () {
+    const services = this.config.services || {}
+    const enabledServices = DevToolsManager.getEnabledServices(services)
+    const spinner = Logger.spinner(`Starting infrastructure services (${enabledServices.join(', ')})`)
+    try {
+      const devToolsPath = this.config.devToolsPath || null
+      // Phase 1: Start infrastructure containers
+      await DevToolsManager.startServices(devToolsPath, services)
+      // Phase 2: Wait for infrastructure to be healthy
+      spinner.text = 'Waiting for infrastructure services to be healthy...'
+      const results = await DevToolsManager.waitForServices(services)
+      const failed = Object.entries(results).filter(([_, s]) => s !== 'healthy')
+      if (failed.length > 0) {
+        const failedNames = failed.map(([name]) => name).join(', ')
+        // Check if any critical service failed
+        const criticalServices = ['postgres', 'redis', 'pubsub']
+        const criticalFailed = failed.some(([name]) =>
+          services[name] && criticalServices.includes(name)
+        )
+        if (criticalFailed) {
+          spinner.fail(`Critical services failed to start: ${failedNames}`)
+          Logger.error('Fix the service issues and try again')
+          Logger.info('Run "docker-compose -f docker-compose.services.yml logs <service>" to debug')
+          process.exit(1)
+        } else {
+          spinner.warn(`Optional services not healthy: ${failedNames}`)
+          spinner.start()
+        }
+      }
+      // Give PostgreSQL extra time to fully initialize after health check passes
+      if (results.postgres === 'healthy') {
+        spinner.text = 'PostgreSQL healthy, allowing initialization to complete...'
+        await new Promise(resolve => setTimeout(resolve, 2000))
+      }
+      // Phase 3: Start dev-tools backend
+      spinner.text = 'Starting dev-tools backend...'
+      await DevToolsManager.startDevTools(devToolsPath, services)
+      spinner.text = 'Waiting for dev-tools to be ready...'
+      await DevToolsManager.waitForReady(90000) // 90 second timeout for first start
+      spinner.succeed('Dev-tools started!')
+    } catch (error) {
+      spinner.fail('Failed to start dev-tools')
+      Logger.error(error.message)
+      Logger.info('\nTry starting manually:')
+      Logger.info('  cd ../dev-tools')
+      Logger.info('  docker-compose -f docker-compose.services.yml up -d')
+      process.exit(1)
+    }
+  }
+
+  async configureAppGateway (spinner) {
+    const appGateway = this.config.appGateway
+    if (!appGateway) return
+    try {
+      if (appGateway.enabled) {
+        if (spinner) spinner.text = 'Configuring App Gateway...'
+        // Check current gateway status
+        const statusResponse = await fetch('http://localhost:9000/v1/gateway/status', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({})
+        })
+        const statusResult = await statusResponse.json()
+        const isRunning = statusResult.data?.state === 'running'
+        const isWaiting = statusResult.data?.state === 'waitingForDependencies'
+        if (isRunning || isWaiting) {
+          if (spinner) spinner.text = `App Gateway is ${isRunning ? 'running' : 'waiting for dependencies'}`
+        } else {
+          // Start the gateway
+          if (spinner) spinner.text = 'Starting App Gateway...'
+          await fetch('http://localhost:9000/v1/gateway/start', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({})
+          })
+          if (spinner) spinner.text = 'App Gateway started'
+        }
+      } else {
+        // Gateway disabled — stop if running
+        if (spinner) spinner.text = 'App Gateway disabled, ensuring stopped...'
+        await fetch('http://localhost:9000/v1/gateway/stop', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({})
+        })
+      }
+    } catch (error) {
+      // Non-fatal — gateway configuration is optional
+      if (spinner) spinner.text = 'App Gateway configuration skipped (dev-tools may not be ready)'
+    }
+  }
+
+  async start () {
+    // Ensure dependencies are installed
+    await this.ensureDependencies()
+    // Ensure MCP config before anything else (doesn't depend on Docker/services)
+    const mcpResult = ensureMcpConfig()
+    await this.promptMcpPermissions()
+    const spinner = Logger.spinner(`Starting ${this.config.name}`)
+    try {
+      // Step 1: Ensure Docker is running first
+      spinner.text = 'Checking Docker...'
+      const dockerRunning = await DockerManager.isRunning()
+      if (!dockerRunning) {
+        spinner.stop()
+        const shouldStartDocker = await this.promptStartDocker()
+        if (!shouldStartDocker) {
+          process.exit(0)
+        }
+        await this.startDockerWithPrompt()
+      }
+      // Step 2: Ensure required services are running
+      const services = this.config.services || {}
+      const enabledServices = DevToolsManager.getEnabledServices(services)
+      const devToolsPath = this.config.devToolsPath || null
+
+      // Always check and start services (even if dev-tools backend is already running)
+      if (enabledServices.length > 0) {
+        spinner.text = `Ensuring infrastructure services (${enabledServices.join(', ')})...`
+        await DevToolsManager.startServices(devToolsPath, services)
+        spinner.text = 'Waiting for infrastructure services to be healthy...'
+        const results = await DevToolsManager.waitForServices(services)
+        const failed = Object.entries(results).filter(([_, s]) => s !== 'healthy')
+        if (failed.length > 0) {
+          const failedNames = failed.map(([name]) => name).join(', ')
+          // Check if any critical service failed
+          const criticalServices = ['postgres', 'redis', 'pubsub']
+          const criticalFailed = failed.some(([name]) =>
+            services[name] && criticalServices.includes(name)
+          )
+          if (criticalFailed) {
+            spinner.fail(`Critical services failed to start: ${failedNames}`)
+            Logger.error('Fix the service issues and try again')
+            Logger.info('Run "docker-compose -f docker-compose.services.yml logs <service>" to debug')
+            process.exit(1)
+          } else {
+            spinner.warn(`Optional services not healthy: ${failedNames}`)
+            spinner.start()
+          }
+        }
+        // Give PostgreSQL extra time to fully initialize after health check passes
+        if (results.postgres === 'healthy') {
+          spinner.text = 'PostgreSQL healthy, allowing initialization to complete...'
+          await new Promise(resolve => setTimeout(resolve, 2000))
+        }
+      }
+
+      // Step 3: Ensure dev-tools backend is running (auto-start if needed)
+      spinner.start('Checking dev-tools status...')
+      const devToolsRunning = await DevToolsChecker.isRunning()
+      if (!devToolsRunning) {
+        spinner.stop()
+        // Ask user if they want to start dev-tools backend
+        const shouldStart = await this.promptStartDevTools()
+        if (!shouldStart) {
+          process.exit(0)
+        }
+        // Start dev-tools backend
+        spinner.start('Starting dev-tools backend...')
+        await DevToolsManager.startDevTools(devToolsPath, services)
+        await DevToolsManager.waitForReady()
+      }
+      // Step 3.5: Verify service dependencies
+      if (this.config.dependencies?.services) {
+        await this.verifyServiceDependencies(spinner)
+      }
+      // Step 4: Ensure Docker network
+      spinner.start('Ensuring Docker network...')
+      await DockerManager.ensureNetwork('goki-network')
+      // Step 4: Initialize database if configured (PostgreSQL only)
+      if (this.config.database) {
+        spinner.text = 'Verifying database setup...'
+        const dbManager = new DatabaseManager({
+          host: 'localhost',
+          port: 5432,
+          user: 'postgres',
+          password: 'postgres',
+          database: this.config.database
+        })
+        const dbReachable = await dbManager.isReachable()
+        if (!dbReachable) {
+          spinner.warn('PostgreSQL not reachable (ensure postgres service is enabled)')
+        } else {
+          const dbExists = await dbManager.databaseExists()
+          if (!dbExists) {
+            spinner.text = 'Creating database...'
+            await dbManager.createDatabase()
+            spinner.text = 'Running schema...'
+            await dbManager.runSchema(this.config.schemaPath)
+            spinner.text = 'Database initialized!'
+          } else {
+            spinner.text = 'Database verified'
+          }
+        }
+      }
+      // Step 5: Initialize Pub/Sub topics and subscriptions if configured
+      if (this.config.pubsub?.topics?.length) {
+        spinner.text = 'Verifying Pub/Sub setup...'
+        const pubsubManager = new PubSubManager(this.config.pubsub)
+        const pubsubReachable = await pubsubManager.isReachable()
+        if (pubsubReachable) {
+          const results = await pubsubManager.initializeAll(this.config.pubsub.topics)
+          const newTopics = results.topics.filter(t => t.result === 'created')
+          const newSubs = results.subscriptions.filter(s => s.result === 'created')
+          if (newTopics.length > 0 || newSubs.length > 0) {
+            spinner.text = `Created ${newTopics.length} topic(s), ${newSubs.length} subscription(s)`
+          }
+          // Register topics with dev-tools for auto-recovery after emulator restart
+          await pubsubManager.registerWithDevTools(this.config.pubsub.topics, this.config.name)
+        } else {
+          spinner.warn('Pub/Sub emulator not reachable (skipping setup)')
+        }
+      }
+      // Step 5.5: Register webhook routes and start ngrok if configured
+      let webhookResult = null
+      if (this.config.webhookProxy?.enabled) {
+        const webhooks = this.config.webhookProxy.routes || {}
+        webhookResult = await NgrokManager.setup(webhooks, spinner, this.config.name)
+      }
+      // Step 5.6: Register Cloud Functions if configured
+      if (this.config.functions?.list?.length) {
+        spinner.text = 'Registering Cloud Functions...'
+        const fnManager = new FunctionManager()
+        const fnReachable = await fnManager.isReachable()
+        if (fnReachable) {
+          const fnResult = await fnManager.registerFunctions(this.config.functions, process.cwd())
+          if (fnResult.registered.length > 0) {
+            spinner.text = `Registered ${fnResult.registered.length} Cloud Function(s)`
+          }
+          if (fnResult.errors.length > 0) {
+            for (const err of fnResult.errors) {
+              Logger.warn(`Function '${err.name}' failed: ${err.error}`)
+            }
+          }
+        } else {
+          spinner.warn('Dev-tools backend not reachable (skipping Cloud Functions setup)')
+        }
+      }
+      // Step 5.7: Compute proxy rewrites (data only)
+      let proxyResult = null
+      if (this.config.httpProxy?.enabled) {
+        spinner.text = 'Computing HTTP proxy rewrites...'
+        proxyResult = computeProxyRewrites(this.config, process.cwd())
+      }
+      // Step 5.7: Compute webhook rewrites (data only)
+      let webhookRewrites = null
+      if (webhookResult?.tunnelUrl) {
+        spinner.text = 'Computing webhook URL substitutions...'
+        const webhookRewriteResult = computeWebhookRewrites(this.config, process.cwd(), webhookResult.tunnelUrl)
+        webhookRewrites = webhookRewriteResult?.rewrites || null
+      }
+      // Step 5.8: Unlock secrets if config.secrets is defined
+      let secretsManager = null
+      let secretEnv = {}
+      if (this.config.secrets) {
+        try {
+          spinner.text = 'Unlocking secrets...'
+          spinner.stop()
+          const { SecretsManager } = await import('./secrets/SecretsManager.js')
+          secretsManager = await SecretsManager.create({ projectDir: process.cwd() })
+          await secretsManager.unlock()
+          secretEnv = secretsManager.getEnvMap()
+          spinner.start()
+          const keyCount = Object.keys(secretEnv).length
+          if (keyCount > 0) {
+            spinner.text = `${keyCount} secrets loaded`
+          }
+        } catch (err) {
+          spinner.start()
+          Logger.warn(`Secrets unlock skipped: ${err.message}`)
+        }
+      }
+      // Step 6: Generate single combined override
+      spinner.text = 'Generating docker-compose override...'
+      const overrideResult = generateComposeOverride(this.config, process.cwd(), {
+        proxyRewrites: proxyResult?.rewrites,
+        webhookRewrites,
+        secretKeys: Object.keys(secretEnv),
+        secretsManager
+      })
+      // Step 7: Start application
+      spinner.text = `Starting ${this.config.name} application...`
+      await DockerManager.composeUp(this.getBaseCompose(), this.getOverrideCompose(), {
+        env: Object.keys(secretEnv).length > 0 ? secretEnv : undefined
+      })
+      if (this.getContainerName()) {
+        spinner.text = 'Waiting for application to be ready...'
+        await DockerManager.waitForHealthy(this.getContainerName(), 30000)
+      }
+      // Step 8: Configure App Gateway if specified
+      await this.configureAppGateway(spinner)
+      spinner.succeed('Setup complete!')
+      // Display beautiful formatted output
+      console.log(formatStartupOutput({
+        projectName: this.config.name,
+        appPort: this.getAppPort(),
+        webhookResult,
+        webhookUrlResult: webhookRewrites ? { rewrites: webhookRewrites } : null,
+        proxyResult,
+        overrideResult,
+        mcpResult
+      }))
+    } catch (error) {
+      spinner.fail('Failed to start')
+      Logger.error(error.message)
+      process.exit(1)
+    }
+  }
+
+  async stop () {
+    const spinner = Logger.spinner(`Stopping ${this.config.name}`)
+    try {
+      await DockerManager.composeStop(this.getBaseCompose(), this.getOverrideCompose())
+      spinner.succeed(`${this.config.name} stopped successfully!`)
+    } catch (error) {
+      spinner.fail('Failed to stop')
+      Logger.error(error.message)
+      process.exit(1)
+    }
+  }
+
+  async status () {
+    try {
+      await DockerManager.composePs(this.getBaseCompose(), this.getOverrideCompose())
+    } catch (error) {
+      Logger.error(error.message)
+      process.exit(1)
+    }
+  }
+
+  async logs (options) {
+    console.clear()
+    console.log('┌─────────────────────────────────────────────────────────────────┐')
+    console.log(`│  📋 Live Logs - ${this.config.name}`.padEnd(67) + '│')
+    console.log('│  Press ESC or q to return to menu'.padEnd(67) + '│')
+    console.log('└─────────────────────────────────────────────────────────────────┘')
+    console.log('')
+    const args = ['-f', this.getBaseCompose(), '-f', this.getOverrideCompose(), 'logs']
+    if (options.follow) {
+      args.push('-f')
+    } else {
+      args.push('--tail=100')
+    }
+    // Spawn docker-compose logs
+    const logsProcess = execa('docker-compose', args, {
+      cwd: process.cwd(),
+      stdio: ['ignore', 'inherit', 'inherit']
+    })
+    // Set up keyboard input
+    let shouldExit = false
+    process.stdin.setRawMode(true)
+    process.stdin.resume()
+    process.stdin.setEncoding('utf8')
+    const keyHandler = (key) => {
+      // ESC, q, or Ctrl+C to exit
+      if (key === '\u001b' || key === 'q' || key === '\u0003') {
+        shouldExit = true
+        logsProcess.kill('SIGTERM')
+      }
+    }
+    process.stdin.on('data', keyHandler)
+    try {
+      await logsProcess
+    } catch (error) {
+      // Process was killed or exited
+      if (!shouldExit && error.signal !== 'SIGTERM' && error.signal !== 'SIGINT') {
+        Logger.error(error.message)
+      }
+    } finally {
+      process.stdin.removeListener('data', keyHandler)
+      process.stdin.setRawMode(false)
+      process.stdin.pause()
+      if (shouldExit) {
+        console.clear()
+      }
+    }
+  }
+
+  requiresDatabase () {
+    if (!this.config.database) {
+      Logger.warn('This project does not use PostgreSQL (no database configured)')
+      Logger.info('This project may use Firestore or another database instead')
+      return false
+    }
+    return true
+  }
+
+  async dbInit () {
+    if (!this.requiresDatabase()) return
+    const spinner = Logger.spinner('Initializing database')
+    try {
+      const dbManager = new DatabaseManager({
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'postgres',
+        database: this.config.database
+      })
+      spinner.text = 'Checking PostgreSQL connection...'
+      const isReachable = await dbManager.isReachable()
+      if (!isReachable) {
+        spinner.fail('PostgreSQL not reachable')
+        Logger.error('Make sure dev-tools is running')
+        process.exit(1)
+      }
+      const exists = await dbManager.databaseExists()
+      if (exists) {
+        spinner.stop()
+        const inquirer = await import('inquirer')
+        const { recreate } = await inquirer.default.prompt([{
+          type: 'confirm',
+          name: 'recreate',
+          message: `Database "${this.config.database}" already exists. Recreate? (all data will be lost)`,
+          default: false
+        }])
+        if (!recreate) {
+          Logger.info('Skipped')
+          return
+        }
+        spinner.start('Dropping existing database...')
+        await dbManager.dropDatabase()
+      }
+      spinner.text = 'Creating database...'
+      await dbManager.createDatabase()
+      spinner.text = `Running schema from ${this.config.schemaPath}...`
+      await dbManager.runSchema(this.config.schemaPath)
+      if (this.config.schemaVerification) {
+        spinner.text = 'Verifying schema...'
+        const verification = await dbManager.verify()
+        const expected = this.config.schemaVerification
+        if (verification.tables === expected.tables &&
+            verification.views === expected.views &&
+            verification.functions === expected.functions) {
+          spinner.succeed('Database initialized successfully!')
+          console.log('\n✅ Schema verified:')
+          console.log(`   Tables: ${verification.tables} (expected: ${expected.tables})`)
+          console.log(`   Views: ${verification.views} (expected: ${expected.views})`)
+          console.log(`   Functions: ${verification.functions} (expected: ${expected.functions})\n`)
+        } else {
+          spinner.fail('Schema verification failed')
+          console.log('\n❌ Schema mismatch:')
+          console.log(`   Tables: ${verification.tables} (expected: ${expected.tables})`)
+          console.log(`   Views: ${verification.views} (expected: ${expected.views})`)
+          console.log(`   Functions: ${verification.functions} (expected: ${expected.functions})\n`)
+          process.exit(1)
+        }
+      } else {
+        spinner.succeed('Database initialized successfully!')
+      }
+      if (this.config.pubsub?.topics?.length) {
+        await this.initializePubSub(spinner)
+      }
+    } catch (error) {
+      spinner.fail('Failed to initialize database')
+      Logger.error(error.message)
+      process.exit(1)
+    }
+  }
+
+  async initializePubSub (spinner) {
+    const pubsubConfig = this.config.pubsub
+    const pubsubManager = new PubSubManager(pubsubConfig)
+    if (spinner) spinner.start('Checking Pub/Sub emulator...')
+    const isReachable = await pubsubManager.isReachable()
+    if (!isReachable) {
+      if (spinner) spinner.warn('Pub/Sub emulator not reachable - skipping')
+      console.log('   Make sure the Pub/Sub emulator is running on port ' + pubsubConfig.port)
+      return
+    }
+    if (spinner) spinner.text = 'Creating Pub/Sub topics and subscriptions...'
+    const results = await pubsubManager.initializeAll(pubsubConfig.topics)
+    // Register topics with dev-tools for auto-recovery after emulator restart
+    await pubsubManager.registerWithDevTools(pubsubConfig.topics, this.config.name)
+    if (spinner) spinner.succeed('Pub/Sub initialized!')
+    console.log('\n\u2705 Pub/Sub resources:')
+    for (const topic of results.topics) {
+      console.log(`   Topic: ${topic.name} (${topic.result})`)
+    }
+    for (const sub of results.subscriptions) {
+      console.log(`   Subscription: ${sub.name} -> ${sub.topic} (${sub.result})`)
+    }
+    console.log('')
+  }
+
+  async pubsubInit () {
+    const spinner = Logger.spinner('Initializing Pub/Sub')
+    try {
+      if (!this.config.pubsub?.topics?.length) {
+        spinner.fail('No Pub/Sub configuration found in .dev-tools/config.js')
+        process.exit(1)
+      }
+      await this.initializePubSub(spinner)
+    } catch (error) {
+      spinner.fail('Failed to initialize Pub/Sub')
+      Logger.error(error.message)
+      process.exit(1)
+    }
+  }
+
+  async dbReset () {
+    if (!this.requiresDatabase()) return
+    try {
+      const inquirer = await import('inquirer')
+      const { confirm } = await inquirer.default.prompt([{
+        type: 'confirm',
+        name: 'confirm',
+        message: `⚠️  This will DELETE all data in "${this.config.database}". Continue?`,
+        default: false
+      }])
+      if (!confirm) {
+        Logger.info('Cancelled')
+        return
+      }
+      const spinner = Logger.spinner('Dropping database')
+      const dbManager = new DatabaseManager({
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'postgres',
+        database: this.config.database
+      })
+      await dbManager.dropDatabase()
+      spinner.text = 'Creating database...'
+      await dbManager.createDatabase()
+      spinner.text = 'Running schema...'
+      await dbManager.runSchema(this.config.schemaPath)
+      spinner.succeed('Database reset successfully!')
+    } catch (error) {
+      Logger.error('Failed to reset database')
+      Logger.error(error.message)
+      process.exit(1)
+    }
+  }
+
+  async dbClear () {
+    if (!this.requiresDatabase()) return
+    try {
+      const inquirer = await import('inquirer')
+      const { confirm } = await inquirer.default.prompt([{
+        type: 'confirm',
+        name: 'confirm',
+        message: `⚠️  This will DELETE all data (but keep schema) in "${this.config.database}". Continue?`,
+        default: false
+      }])
+      if (!confirm) {
+        Logger.info('Cancelled')
+        return
+      }
+      const spinner = Logger.spinner('Clearing database')
+      const dbManager = new DatabaseManager({
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'postgres',
+        database: this.config.database
+      })
+      await dbManager.clear()
+      spinner.succeed('Database cleared successfully!')
+    } catch (error) {
+      Logger.error('Failed to clear database')
+      Logger.error(error.message)
+      process.exit(1)
+    }
+  }
+
+  async setup () {
+    // Ensure dependencies are installed
+    await this.ensureDependencies()
+    // Ensure MCP config before anything else (doesn't depend on Docker/services)
+    const mcpResult = ensureMcpConfig()
+    await this.promptMcpPermissions()
+    const spinner = Logger.spinner(`Setting up ${this.config.name}`)
+    try {
+      // Step 1: Ensure Docker is running
+      spinner.text = 'Checking Docker...'
+      const dockerResult = await DockerManager.ensureRunning()
+      if (dockerResult.wasStarted) {
+        spinner.text = 'Docker started, initializing services...'
+      }
+      // Step 2: Ensure required services are running
+      const services = this.config.services || {}
+      const enabledServices = DevToolsManager.getEnabledServices(services)
+      const devToolsPath = this.config.devToolsPath || null
+
+      // Always check and start services (even if dev-tools is already running)
+      if (enabledServices.length > 0) {
+        spinner.text = `Ensuring infrastructure services (${enabledServices.join(', ')})...`
+        await DevToolsManager.startServices(devToolsPath, services)
+        spinner.text = 'Waiting for infrastructure services to be healthy...'
+        const results = await DevToolsManager.waitForServices(services)
+        const failed = Object.entries(results).filter(([_, s]) => s !== 'healthy')
+        if (failed.length > 0) {
+          const failedNames = failed.map(([name]) => name).join(', ')
+          // Check if any critical service failed
+          const criticalServices = ['postgres', 'redis', 'pubsub']
+          const criticalFailed = failed.some(([name]) =>
+            services[name] && criticalServices.includes(name)
+          )
+          if (criticalFailed) {
+            spinner.fail(`Critical services failed to start: ${failedNames}`)
+            Logger.error('Fix the service issues and try again')
+            Logger.info('Run "docker-compose -f docker-compose.services.yml logs <service>" to debug')
+            process.exit(1)
+          } else {
+            spinner.warn(`Optional services not healthy: ${failedNames}`)
+            spinner.start()
+          }
+        }
+        // Give PostgreSQL extra time to fully initialize after health check passes
+        if (results.postgres === 'healthy') {
+          spinner.text = 'PostgreSQL healthy, allowing initialization to complete...'
+          await new Promise(resolve => setTimeout(resolve, 2000))
+        }
+      }
+
+      // Step 3: Ensure dev-tools backend is running (auto-start if needed)
+      spinner.text = 'Checking dev-tools backend...'
+      const devToolsRunning = await DevToolsManager.isRunning()
+      if (!devToolsRunning) {
+        spinner.text = 'Starting dev-tools backend...'
+        await DevToolsManager.startDevTools(devToolsPath, services)
+        await DevToolsManager.waitForReady()
+        spinner.text = 'Dev-tools started!'
+      }
+      // Step 4: Ensure Docker network exists
+      spinner.text = 'Ensuring Docker network...'
+      await DockerManager.ensureNetwork('goki-network')
+      // Step 5: Check and initialize database if needed (only for PostgreSQL projects)
+      if (this.config.database) {
+        spinner.text = 'Checking database...'
+        const dbManager = new DatabaseManager({
+          host: 'localhost',
+          port: 5432,
+          user: 'postgres',
+          password: 'postgres',
+          database: this.config.database
+        })
+        const dbReachable = await dbManager.isReachable()
+        if (!dbReachable) {
+          spinner.fail('PostgreSQL not reachable')
+          Logger.error('Dev-tools started but PostgreSQL is not responding')
+          process.exit(1)
+        }
+        const dbExists = await dbManager.databaseExists()
+        if (!dbExists) {
+          spinner.text = 'Creating database...'
+          await dbManager.createDatabase()
+          spinner.text = 'Running schema...'
+          await dbManager.runSchema(this.config.schemaPath)
+          spinner.text = 'Database initialized!'
+        }
+      }
+      // Step 5: Initialize Pub/Sub if configured
+      if (this.config.pubsub?.topics?.length) {
+        spinner.text = 'Verifying Pub/Sub setup...'
+        const pubsubManager = new PubSubManager(this.config.pubsub)
+        const pubsubReachable = await pubsubManager.isReachable()
+        if (pubsubReachable) {
+          const results = await pubsubManager.initializeAll(this.config.pubsub.topics)
+          const newTopics = results.topics.filter(t => t.result === 'created')
+          const newSubs = results.subscriptions.filter(s => s.result === 'created')
+          if (newTopics.length > 0 || newSubs.length > 0) {
+            spinner.text = `Created ${newTopics.length} topic(s), ${newSubs.length} subscription(s)`
+          } else {
+            spinner.text = 'Pub/Sub setup verified (all exist)'
+          }
+          // Register topics with dev-tools for auto-recovery after emulator restart
+          await pubsubManager.registerWithDevTools(this.config.pubsub.topics, this.config.name)
+        } else {
+          spinner.warn('Pub/Sub emulator not reachable (skipping)')
+        }
+      }
+      // Step 5.5: Register webhook routes and start ngrok if configured
+      let webhookResult = null
+      if (this.config.webhookProxy?.enabled) {
+        const webhooks = this.config.webhookProxy.routes || {}
+        webhookResult = await NgrokManager.setup(webhooks, spinner, this.config.name)
+      }
+      // Step 5.6: Compute proxy rewrites (data only)
+      let proxyResult = null
+      if (this.config.httpProxy?.enabled) {
+        spinner.text = 'Computing HTTP proxy rewrites...'
+        proxyResult = computeProxyRewrites(this.config, process.cwd())
+      }
+      // Step 5.7: Compute webhook rewrites (data only)
+      let webhookRewrites = null
+      if (webhookResult?.tunnelUrl) {
+        spinner.text = 'Computing webhook URL substitutions...'
+        const webhookRewriteResult = computeWebhookRewrites(this.config, process.cwd(), webhookResult.tunnelUrl)
+        webhookRewrites = webhookRewriteResult?.rewrites || null
+      }
+      // Step 6: Generate single combined override
+      spinner.text = 'Generating docker-compose override...'
+      const overrideResult = generateComposeOverride(this.config, process.cwd(), {
+        proxyRewrites: proxyResult?.rewrites,
+        webhookRewrites
+      })
+      // Step 7: Start the application in Docker
+      spinner.text = `Starting ${this.config.name}...`
+      await DockerManager.composeUp(this.getBaseCompose(), this.getOverrideCompose())
+      if (this.getContainerName()) {
+        spinner.text = 'Waiting for application to be ready...'
+        await DockerManager.waitForHealthy(this.getContainerName(), 30000)
+      } else {
+        // Wait a moment for app to start
+        await new Promise(resolve => setTimeout(resolve, 2000))
+      }
+      // Step 8: Configure App Gateway if specified
+      await this.configureAppGateway(spinner)
+      spinner.succeed('Setup complete!')
+      // Display beautiful formatted output
+      console.log(formatStartupOutput({
+        projectName: this.config.name,
+        appPort: this.getAppPort(),
+        webhookResult,
+        webhookUrlResult: webhookRewrites ? { rewrites: webhookRewrites } : null,
+        proxyResult,
+        overrideResult,
+        mcpResult
+      }))
+    } catch (error) {
+      spinner.fail('Setup failed')
+      Logger.error(error.message)
+      process.exit(1)
+    }
+  }
+
+  async shutdown (options = {}) {
+    try {
+      // If flags are provided, use them directly
+      if (options.app) {
+        return await this.stopApp()
+      }
+      if (options.all) {
+        return await this.shutdownAll()
+      }
+      if (options.reset) {
+        return await this.resetDatabase()
+      }
+      if (options.cleanup) {
+        return await this.fullCleanup()
+      }
+      // No flags: show interactive menu
+      const inquirer = await import('inquirer')
+      console.log('')
+      const choices = [
+        { name: `Stop ${this.config.name} only`, value: 'app' }
+      ]
+      if (this.config.database) {
+        choices.push({ name: `Stop ${this.config.name} + drop database`, value: 'app-and-db' })
+      }
+      choices.push(
+        new inquirer.default.Separator(),
+        { name: 'Stop dev-tools (affects all projects)', value: 'devtools' },
+        { name: 'Stop everything + cleanup all data', value: 'all' },
+        new inquirer.default.Separator(),
+        { name: '← Back to menu', value: 'cancel' }
+      )
+      const { action } = await inquirer.default.prompt([{
+        type: 'list',
+        name: 'action',
+        message: 'What would you like to stop?',
+        choices,
+        loop: false,
+        pageSize: 10
+      }])
+      switch (action) {
+        case 'app': return await this.stopApp()
+        case 'app-and-db': return await this.fullCleanup()
+        case 'devtools': return await this.shutdownDevToolsOnly()
+        case 'all': return await this.shutdownAll()
+        case 'cancel':
+          Logger.info('Cancelled')
+      }
+    } catch (error) {
+      Logger.error(error.message)
+      process.exit(1)
+    }
+  }
+
+  async stopApp () {
+    const spinner = Logger.spinner(`Stopping ${this.config.name}`)
+    try {
+      await DockerManager.composeStop(this.getBaseCompose(), this.getOverrideCompose())
+      if (this.config.webhooks && Object.keys(this.config.webhooks).length > 0) {
+        spinner.text = 'Stopping ngrok tunnel...'
+        await NgrokManager.stop()
+      }
+      spinner.succeed(`${this.config.name} stopped`)
+    } catch (error) {
+      spinner.fail('Failed to stop')
+      Logger.error(error.message)
+    }
+  }
+
+  async stopAll () {
+    const spinner = Logger.spinner('Stopping project + dev-tools')
+    try {
+      spinner.text = `Stopping ${this.config.name}...`
+      await this.stopApp()
+      spinner.stop()
+      console.log('\n🛑 Stopping dev-tools...\n')
+      await DevToolsManager.stop(this.config.devToolsPath)
+      console.log('\n✅ All services stopped\n')
+      Logger.info('Note: Database was not dropped')
+    } catch (error) {
+      Logger.error('\n❌ Failed to stop services')
+      Logger.error(error.message)
+    }
+  }
+
+  async resetDatabase () {
+    if (!this.requiresDatabase()) return
+    try {
+      const inquirer = await import('inquirer')
+      const { confirm } = await inquirer.default.prompt([{
+        type: 'confirm',
+        name: 'confirm',
+        message: `⚠️  This will DELETE all data in "${this.config.database}". Continue?`,
+        default: false
+      }])
+      if (!confirm) {
+        Logger.info('Cancelled')
+        return
+      }
+      const spinner = Logger.spinner('Clearing database')
+      const dbManager = new DatabaseManager({
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'postgres',
+        database: this.config.database
+      })
+      await dbManager.clear()
+      spinner.succeed('Database reset (data cleared, schema intact)')
+    } catch (error) {
+      Logger.error('Failed to reset database')
+      Logger.error(error.message)
+    }
+  }
+
+  async fullCleanup () {
+    try {
+      const inquirer = await import('inquirer')
+      const warningMsg = this.config.database
+        ? `⚠️  This will STOP ${this.config.name} and DROP the database "${this.config.database}". Continue?`
+        : `⚠️  This will STOP ${this.config.name} application. Continue?`
+      const { confirm } = await inquirer.default.prompt([{
+        type: 'confirm',
+        name: 'confirm',
+        message: warningMsg,
+        default: false
+      }])
+      if (!confirm) {
+        Logger.info('Cancelled')
+        return
+      }
+      const spinner = Logger.spinner(`Stopping ${this.config.name}`)
+      await this.stopApp()
+      if (this.config.database) {
+        spinner.text = 'Dropping database...'
+        const dbManager = new DatabaseManager({
+          host: 'localhost',
+          port: 5432,
+          user: 'postgres',
+          password: 'postgres',
+          database: this.config.database
+        })
+        try {
+          await dbManager.dropDatabase()
+        } catch {
+          // Database might not exist
+        }
+      }
+      spinner.succeed('Project cleanup complete')
+      Logger.info('\nNote: Dev-tools is still running (shared service)')
+      Logger.info('To stop dev-tools: goki-dev shutdown\n')
+    } catch (error) {
+      Logger.error('Failed to cleanup')
+      Logger.error(error.message)
+    }
+  }
+
+  async shutdownAll () {
+    try {
+      const inquirer = await import('inquirer')
+      const warningMsg = this.config.database
+        ? `⚠️  This will STOP ${this.config.name}, DROP database, and STOP dev-tools (affects all projects). Continue?`
+        : `⚠️  This will STOP ${this.config.name} and STOP dev-tools (affects all projects). Continue?`
+      const { confirm } = await inquirer.default.prompt([{
+        type: 'confirm',
+        name: 'confirm',
+        message: warningMsg,
+        default: false
+      }])
+      if (!confirm) {
+        Logger.info('Cancelled')
+        return
+      }
+      const spinner = Logger.spinner(`Stopping ${this.config.name}`)
+      await this.stopApp()
+      if (this.config.database) {
+        spinner.text = 'Dropping database...'
+        const dbManager = new DatabaseManager({
+          host: 'localhost',
+          port: 5432,
+          user: 'postgres',
+          password: 'postgres',
+          database: this.config.database
+        })
+        try {
+          await dbManager.dropDatabase()
+        } catch {
+          // Database might not exist
+        }
+      }
+      spinner.stop()
+      console.log('\n🛑 Stopping dev-tools...\n')
+      await DevToolsManager.stop(this.config.devToolsPath)
+      console.log('\n✅ All services stopped\n')
+    } catch (error) {
+      Logger.error('\n❌ Failed to shutdown')
+      Logger.error(error.message)
+    }
+  }
+
+  async shutdownDevToolsOnly () {
+    try {
+      const inquirer = await import('inquirer')
+      const { confirm } = await inquirer.default.prompt([{
+        type: 'confirm',
+        name: 'confirm',
+        message: '⚠️  This will STOP dev-tools (affects all projects using dev-tools). Continue?',
+        default: false
+      }])
+      if (!confirm) {
+        Logger.info('Cancelled')
+        return
+      }
+      console.log('\n🛑 Stopping dev-tools...\n')
+      await DevToolsManager.stop(this.config.devToolsPath)
+      console.log('\n✅ Dev-tools stopped\n')
+      Logger.info('Note: Your project app may still be running')
+      Logger.info(`To stop ${this.config.name}: goki-dev stop\n`)
+    } catch (error) {
+      Logger.error('\n❌ Failed to stop dev-tools')
+      Logger.error(error.message)
+    }
+  }
+
+  async menu () {
+    const inquirer = await import('inquirer')
+    while (true) {
+      console.clear()
+      console.log(`\n🔧 ${this.config.name} Development CLI\n`)
+      const choices = [
+        { name: '🚀  Start development environment', value: 'start' },
+        { name: '🛑  Stop services', value: 'stop' },
+        new inquirer.default.Separator(),
+        { name: '🧪  Run e2e tests (snapshot/restore)', value: 'e2e' },
+        { name: '⚡  Run tests (no snapshot)', value: 'test' },
+        new inquirer.default.Separator(),
+        { name: '📊  Live Dashboard (real-time status)', value: 'dashboard' },
+        { name: '📋  View logs (live)', value: 'logs' },
+        { name: '🔍  Check service status', value: 'status' }
+      ]
+      // Add database/pubsub options if configured
+      if (this.config.database || this.config.pubsub?.topics?.length) {
+        choices.push(new inquirer.default.Separator())
+        if (this.config.database) {
+          choices.push({ name: '🗄️   Database operations', value: 'database' })
+        }
+        if (this.config.pubsub?.topics?.length) {
+          choices.push({ name: '📨  Pub/Sub operations', value: 'pubsub' })
+        }
+      }
+      choices.push(
+        new inquirer.default.Separator(),
+        { name: '🔐  Secrets management', value: 'secrets' },
+        new inquirer.default.Separator(),
+        { name: '❌  Exit', value: 'exit' }
+      )
+      const { action } = await inquirer.default.prompt([{
+        type: 'list',
+        name: 'action',
+        message: 'What would you like to do?',
+        choices,
+        loop: false,
+        pageSize: 12
+      }])
+      switch (action) {
+        case 'start':
+          await this.setup()
+          return
+        case 'stop':
+          await this.shutdown()
+          break
+        case 'e2e':
+          await this.e2eMenu()
+          break
+        case 'test':
+          await this.runTestsDirectly()
+          break
+        case 'dashboard':
+          await this.liveDashboard()
+          break
+        case 'logs':
+          await this.logs({ follow: true })
+          return
+        case 'status':
+          await this.showStatus()
+          console.log('')
+          break
+        case 'database':
+          await this.databaseMenu()
+          break
+        case 'pubsub':
+          await this.pubsubMenu()
+          break
+        case 'secrets':
+          await this.secretsMenu()
+          break
+        case 'exit':
+          console.log('\n👋 Goodbye!\n')
+          return
+      }
+    }
+  }
+
+  async testsMenu () {
+    const inquirer = await import('inquirer')
+    const { action } = await inquirer.default.prompt([{
+      type: 'list',
+      name: 'action',
+      message: 'Run tests:',
+      choices: [
+        { name: '🧪 All tests', value: 'all' },
+        { name: '⚡ All tests (parallel)', value: 'parallel' },
+        { name: '🌐 API tests only', value: 'api' },
+        { name: '🧠 Logic tests only', value: 'logic' },
+        { name: '📨 Pub/Sub tests only', value: 'pubsub' },
+        new inquirer.default.Separator(),
+        { name: '← Back', value: 'back' }
+      ]
+    }])
+    if (action === 'back') return
+    await this.runTests(action)
+  }
+
+  async runTests (type) {
+    const testCommands = {
+      all: ['tests/component/app/**/*.js', 'tests/component/logic/**/*.js', 'tests/component/subscribers/**/*.js'],
+      parallel: ['-p', 'tests/component/app/**/*.js', 'tests/component/logic/**/*.js', 'tests/component/subscribers/**/*.js'],
+      api: ['tests/component/app/**/*.js'],
+      logic: ['tests/component/logic/**/*.js'],
+      pubsub: ['tests/component/subscribers/**/*.js']
+    }
+    const args = testCommands[type] || testCommands.all
+    const testEnvFile = this.config.testEnvFile || 'config.test'
+    console.log(`\n🧪 Running ${type} tests...\n`)
+    try {
+      await execa('npx', ['dotenv', '-e', testEnvFile, '--', 'mocha', ...args], {
+        stdio: 'inherit'
+      })
+      console.log('')
+    } catch (error) {
+      // Test failures are shown by mocha, just add spacing
+      console.log('')
+    }
+  }
+
+  async showStatus () {
+    console.log('')
+    const checks = []
+    // Check Docker
+    const dockerRunning = await DockerManager.isRunning()
+    checks.push({
+      name: 'Docker',
+      status: dockerRunning ? '✓' : '✗',
+      color: dockerRunning ? 'green' : 'red'
+    })
+    // Check dev-tools
+    const devToolsRunning = await DevToolsManager.isRunning()
+    checks.push({
+      name: 'Dev-tools',
+      status: devToolsRunning ? '✓' : '✗',
+      color: devToolsRunning ? 'green' : 'red'
+    })
+    // Check PostgreSQL (only if this project uses it)
+    if (this.config.database) {
+      const dbManager = new DatabaseManager({
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'postgres',
+        database: this.config.database
+      })
+      const pgReachable = await dbManager.isReachable()
+      checks.push({
+        name: 'PostgreSQL',
+        status: pgReachable ? '✓' : '✗',
+        color: pgReachable ? 'green' : 'red'
+      })
+      // Check database exists
+      if (pgReachable) {
+        const dbExists = await dbManager.databaseExists()
+        checks.push({
+          name: `Database (${this.config.database})`,
+          status: dbExists ? '✓' : '✗',
+          color: dbExists ? 'green' : 'yellow'
+        })
+      }
+    }
+    // Check Pub/Sub
+    if (this.config.pubsub) {
+      const pubsubManager = new PubSubManager(this.config.pubsub)
+      const pubsubReachable = await pubsubManager.isReachable()
+      checks.push({
+        name: 'Pub/Sub Emulator',
+        status: pubsubReachable ? '✓' : '✗',
+        color: pubsubReachable ? 'green' : 'red'
+      })
+    }
+    // Check Firestore (if enabled in services)
+    if (this.config.services?.firestore) {
+      try {
+        const response = await fetch('http://localhost:8080')
+        checks.push({
+          name: 'Firestore Emulator',
+          status: response.ok ? '✓' : '✗',
+          color: response.ok ? 'green' : 'red'
+        })
+      } catch {
+        checks.push({
+          name: 'Firestore Emulator',
+          status: '✗',
+          color: 'red'
+        })
+      }
+    }
+    // Check Redis (if enabled in services, default true)
+    if (this.config.services?.redis !== false) {
+      try {
+        const response = await fetch('http://localhost:9000/v1/redis/connection/test', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({})
+        })
+        const result = await response.json()
+        checks.push({
+          name: 'Redis',
+          status: result.success ? '✓' : '✗',
+          color: result.success ? 'green' : 'red'
+        })
+      } catch {
+        checks.push({
+          name: 'Redis',
+          status: '✗',
+          color: 'red'
+        })
+      }
+    }
+    // Check ngrok tunnel (if webhooks configured)
+    if (this.config.webhooks && Object.keys(this.config.webhooks).length > 0) {
+      const ngrokStatus = await NgrokManager.getStatus()
+      checks.push({
+        name: ngrokStatus.running && ngrokStatus.url ? `ngrok (${ngrokStatus.url})` : 'ngrok Tunnel',
+        status: ngrokStatus.running ? '✓' : '✗',
+        color: ngrokStatus.running ? 'green' : 'yellow'
+      })
+    }
+    console.log('  📊 Service Status:\n')
+    for (const check of checks) {
+      const icon = check.status === '✓' ? '✅' : (check.status === '✗' ? '❌' : '⚠️')
+      const statusText = check.status === '✓' ? 'Running' : 'Stopped'
+      console.log(`    ${icon}  ${check.name.padEnd(25)} ${statusText}`)
+    }
+    console.log('')
+  }
+
+  async liveDashboard () {
+    let isRunning = true
+    let lastRefresh = new Date()
+    // Set up keyboard input
+    process.stdin.setRawMode(true)
+    process.stdin.resume()
+    process.stdin.setEncoding('utf8')
+    const keyHandler = (key) => {
+      // Ctrl+C or q or ESC to exit
+      if (key === '\u0003' || key === 'q' || key === '\u001b') {
+        isRunning = false
+      }
+      // r to refresh immediately
+      if (key === 'r') {
+        lastRefresh = new Date(0) // Force refresh
+      }
+    }
+    process.stdin.on('data', keyHandler)
+    const cleanup = () => {
+      process.stdin.removeListener('data', keyHandler)
+      process.stdin.setRawMode(false)
+      process.stdin.pause()
+    }
+    try {
+      // eslint-disable-next-line no-unmodified-loop-condition
+      while (isRunning) {
+        const now = new Date()
+        const elapsed = now - lastRefresh
+        // Refresh every 3 seconds
+        if (elapsed >= 3000) {
+          console.clear()
+          await this.renderDashboard()
+          lastRefresh = now
+        }
+        // Sleep for 100ms to avoid busy loop
+        await new Promise(resolve => setTimeout(resolve, 100))
+      }
+    } finally {
+      cleanup()
+      console.clear()
+    }
+  }
+
+  async renderDashboard () {
+    const now = new Date()
+    const timeStr = now.toLocaleTimeString()
+    // Header
+    console.log('┌─────────────────────────────────────────────────────────────────┐')
+    console.log(`│  🔧 ${this.config.name} - Live Service Monitor`.padEnd(67) + '│')
+    console.log(`│  Updated: ${timeStr} (refreshing every 3s)`.padEnd(67) + '│')
+    console.log('└─────────────────────────────────────────────────────────────────┘')
+    console.log('')
+    // Collect service status
+    const services = []
+    // Docker
+    const dockerRunning = await DockerManager.isRunning()
+    services.push({
+      name: 'Docker',
+      status: dockerRunning ? 'Running' : 'Stopped',
+      icon: dockerRunning ? '✅' : '❌',
+      port: '-'
+    })
+    // Dev-tools
+    const devToolsRunning = await DevToolsManager.isRunning()
+    services.push({
+      name: 'Dev-tools',
+      status: devToolsRunning ? 'Running' : 'Stopped',
+      icon: devToolsRunning ? '✅' : '❌',
+      port: '9000'
+    })
+    // PostgreSQL (if configured)
+    if (this.config.database) {
+      const dbManager = new DatabaseManager({
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'postgres',
+        database: this.config.database
+      })
+      const pgReachable = await dbManager.isReachable()
+      services.push({
+        name: 'PostgreSQL',
+        status: pgReachable ? 'Running' : 'Stopped',
+        icon: pgReachable ? '✅' : '❌',
+        port: '5432'
+      })
+      if (pgReachable) {
+        const dbExists = await dbManager.databaseExists()
+        services.push({
+          name: `Database (${this.config.database})`,
+          status: dbExists ? 'Ready' : 'Not created',
+          icon: dbExists ? '✅' : '⚠️',
+          port: '-'
+        })
+      }
+    }
+    // Pub/Sub (if configured)
+    if (this.config.pubsub) {
+      const pubsubManager = new PubSubManager(this.config.pubsub)
+      const pubsubReachable = await pubsubManager.isReachable()
+      services.push({
+        name: 'Pub/Sub Emulator',
+        status: pubsubReachable ? 'Running' : 'Stopped',
+        icon: pubsubReachable ? '✅' : '❌',
+        port: '8085'
+      })
+    }
+    // Redis (if enabled)
+    if (this.config.services?.redis !== false) {
+      try {
+        const response = await fetch('http://localhost:9000/v1/redis/connection/test', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({})
+        })
+        const result = await response.json()
+        services.push({
+          name: 'Redis',
+          status: result.success ? 'Running' : 'Stopped',
+          icon: result.success ? '✅' : '❌',
+          port: '6379'
+        })
+      } catch {
+        services.push({
+          name: 'Redis',
+          status: 'Stopped',
+          icon: '❌',
+          port: '6379'
+        })
+      }
+    }
+    // Firestore (if enabled)
+    if (this.config.services?.firestore) {
+      try {
+        const response = await fetch('http://localhost:8080')
+        services.push({
+          name: 'Firestore Emulator',
+          status: response.ok ? 'Running' : 'Stopped',
+          icon: response.ok ? '✅' : '❌',
+          port: '8080'
+        })
+      } catch {
+        services.push({
+          name: 'Firestore Emulator',
+          status: 'Stopped',
+          icon: '❌',
+          port: '8080'
+        })
+      }
+    }
+    // Application container (if configured)
+    if (this.getContainerName()) {
+      try {
+        const { stdout } = await execa('docker', ['inspect', '--format', '{{.State.Status}}', this.getContainerName()])
+        const isRunning = stdout.trim() === 'running'
+        services.push({
+          name: this.config.name,
+          status: isRunning ? 'Running' : 'Stopped',
+          icon: isRunning ? '✅' : '❌',
+          port: this.getAppPort() || '-'
+        })
+      } catch {
+        services.push({
+          name: this.config.name,
+          status: 'Stopped',
+          icon: '❌',
+          port: this.getAppPort() || '-'
+        })
+      }
+    }
+    // ngrok tunnel (if webhooks configured)
+    if (this.config.webhooks && Object.keys(this.config.webhooks).length > 0) {
+      const ngrokStatus = await NgrokManager.getStatus()
+      services.push({
+        name: ngrokStatus.running && ngrokStatus.url ? `ngrok (${ngrokStatus.url})` : 'ngrok Tunnel',
+        status: ngrokStatus.running ? 'Running' : 'Stopped',
+        icon: ngrokStatus.running ? '✅' : '⚠️',
+        port: '4040'
+      })
+    }
+    // Table header
+    console.log('Service'.padEnd(30) + 'Status'.padEnd(15) + 'Port')
+    console.log('─'.repeat(65))
+    // Table rows
+    for (const service of services) {
+      const nameCol = `${service.icon}  ${service.name}`.padEnd(30)
+      const statusCol = service.status.padEnd(15)
+      const portCol = String(service.port)
+      console.log(nameCol + statusCol + portCol)
+    }
+    console.log('')
+    console.log("Press 'q' or ESC to return to menu | 'r' to refresh now")
+  }
+
+  async databaseMenu () {
+    if (!this.requiresDatabase()) return
+    const inquirer = await import('inquirer')
+    console.log('')
+    const { action } = await inquirer.default.prompt([{
+      type: 'list',
+      name: 'action',
+      message: 'Database operations:',
+      choices: [
+        { name: '🏗️   Initialize database (create + run schema)', value: 'init' },
+        { name: '🔄  Clear all data (keep schema)', value: 'reset' },
+        { name: '💣  Drop database completely', value: 'drop' },
+        new inquirer.default.Separator(),
+        { name: '← Back to menu', value: 'back' }
+      ],
+      loop: false,
+      pageSize: 8
+    }])
+    switch (action) {
+      case 'init':
+        await this.dbInit()
+        break
+      case 'reset':
+        await this.resetDatabase()
+        break
+      case 'drop':
+        await this.dropDatabaseInteractive()
+        break
+      case 'back':
+    }
+  }
+
+  async dropDatabaseInteractive () {
+    if (!this.requiresDatabase()) return
+    const inquirer = await import('inquirer')
+    const { confirm } = await inquirer.default.prompt([{
+      type: 'confirm',
+      name: 'confirm',
+      message: `⚠️  This will DROP the database "${this.config.database}". Continue?`,
+      default: false
+    }])
+    if (!confirm) {
+      Logger.info('Cancelled')
+      return
+    }
+    const spinner = Logger.spinner('Dropping database')
+    try {
+      const dbManager = new DatabaseManager({
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'postgres',
+        database: this.config.database
+      })
+      await dbManager.dropDatabase()
+      spinner.succeed('Database dropped')
+    } catch (error) {
+      spinner.fail('Failed to drop database')
+      Logger.error(error.message)
+    }
+  }
+
+  async pubsubMenu () {
+    const inquirer = await import('inquirer')
+    console.log('')
+    const { action } = await inquirer.default.prompt([{
+      type: 'list',
+      name: 'action',
+      message: 'Pub/Sub operations:',
+      choices: [
+        { name: '🏗️   Initialize topics & subscriptions', value: 'init' },
+        { name: '📋  List configured topics', value: 'list' },
+        new inquirer.default.Separator(),
+        { name: '← Back to menu', value: 'back' }
+      ],
+      loop: false,
+      pageSize: 8
+    }])
+    switch (action) {
+      case 'init':
+        await this.pubsubInit()
+        break
+      case 'list':
+        this.listTopics()
+        break
+      case 'back':
+    }
+  }
+
+  listTopics () {
+    if (!this.config.pubsub?.topics?.length) {
+      console.log('\n  No topics configured.\n')
+      return
+    }
+    console.log('\n  Configured topics:')
+    for (const entry of this.config.pubsub.topics) {
+      if (typeof entry === 'string') {
+        console.log(`    📨 ${entry}`)
+      } else {
+        const sub = entry.subscription ? ` → ${entry.subscription}` : ''
+        console.log(`    📨 ${entry.name}${sub}`)
+      }
+    }
+    console.log('')
+  }
+
+  async secretsMenu () {
+    const inquirer = await import('inquirer')
+    console.log('')
+    const { action } = await inquirer.default.prompt([{
+      type: 'list',
+      name: 'action',
+      message: 'Secrets management:',
+      choices: [
+        { name: '📋  List secrets', value: 'list' },
+        { name: '➕  Set a secret', value: 'set' },
+        { name: '🔍  Check required secrets', value: 'check' },
+        { name: '🛠️   Setup missing secrets', value: 'setup' },
+        { name: '🩺  Scan for plaintext credentials', value: 'doctor' },
+        new inquirer.default.Separator(),
+        { name: '← Back to menu', value: 'back' }
+      ],
+      loop: false,
+      pageSize: 10
+    }])
+    if (action === 'back') return
+    const { SecretsManager } = await import('./secrets/SecretsManager.js')
+    try {
+      if (action === 'doctor') {
+        const { SecretsDoctor } = await import('./secrets/SecretsDoctor.js')
+        const doctor = new SecretsDoctor(process.cwd())
+        const findings = await doctor.scan()
+        doctor.report(findings)
+        return
+      }
+      const manager = await SecretsManager.create({ projectDir: process.cwd() })
+      if (action === 'list') {
+        const entries = manager.list()
+        if (entries.length === 0) {
+          console.log('\n  No secrets found.\n')
+        } else {
+          console.log('')
+          for (const e of entries) {
+            const scope = e.scope === 'global' ? 'global' : `project: ${e.project}`
+            console.log(`  ${e.key.padEnd(30)} (${scope})`)
+          }
+          console.log('')
+        }
+        return
+      }
+      await manager.unlock()
+      if (action === 'set') {
+        const { key } = await inquirer.default.prompt([{ type: 'input', name: 'key', message: 'Secret key name:' }])
+        const { value } = await inquirer.default.prompt([{ type: 'password', name: 'value', message: 'Value:', mask: '\u25CF' }])
+        await manager.set(key, value)
+        Logger.success(`set ${key}`)
+      } else if (action === 'check') {
+        const { SecretsConfig } = await import('./secrets/SecretsConfig.js')
+        const cfg = new SecretsConfig(manager)
+        await cfg.check()
+      } else if (action === 'setup') {
+        const { SecretsConfig } = await import('./secrets/SecretsConfig.js')
+        const cfg = new SecretsConfig(manager)
+        await cfg.setup()
+      }
+    } catch (err) {
+      Logger.error(err.message)
+    }
+  }
+
+  // Testing Methods
+
+  async runTestsDirectly () {
+    const testCommand = this.config.e2e?.testCommand || 'npm run test:e2e'
+    const timeout = this.config.e2e?.timeout || 300000
+    console.log(`\n🧪 Running tests: ${testCommand}\n`)
+    try {
+      await execa('sh', ['-c', testCommand], {
+        cwd: process.cwd(),
+        stdio: 'inherit',
+        timeout
+      })
+      console.log('\n✅ Tests passed!\n')
+    } catch (error) {
+      console.log('\n❌ Tests failed\n')
+      process.exit(1)
+    }
+  }
+
+  // E2E Testing Methods
+
+  async e2eMenu () {
+    const inquirer = await import('inquirer')
+    console.log('')
+    const { action } = await inquirer.default.prompt([{
+      type: 'list',
+      name: 'action',
+      message: 'E2E Testing (Snapshot/Restore):',
+      choices: [
+        { name: '🧪  Run e2e tests (snapshot → test → restore)', value: 'run' },
+        { name: '📸  Create snapshot (manual)', value: 'snapshot' },
+        { name: '🔄  Restore snapshot', value: 'restore' },
+        { name: '📋  List snapshots', value: 'list' },
+        { name: '🗑️   Cleanup snapshots', value: 'cleanup' },
+        new inquirer.default.Separator(),
+        { name: '← Back to menu', value: 'back' }
+      ],
+      loop: false,
+      pageSize: 10
+    }])
+    switch (action) {
+      case 'run':
+        await this.e2eRun()
+        break
+      case 'snapshot':
+        await this.e2eSnapshot()
+        break
+      case 'restore':
+        await this.e2eRestoreInteractive()
+        break
+      case 'list':
+        await this.e2eList()
+        break
+      case 'cleanup':
+        await this.e2eCleanupInteractive()
+        break
+      case 'back':
+    }
+  }
+
+  async e2eRestoreInteractive () {
+    const snapshotManager = new SnapshotManager(this.config)
+    try {
+      const result = await snapshotManager.listSnapshots()
+      const snapshots = result.snapshots || []
+      if (snapshots.length === 0) {
+        console.log('\nNo snapshots found.\n')
+        return
+      }
+      const inquirer = await import('inquirer')
+      const choices = snapshots.map(s => ({
+        name: `${s.id} - ${new Date(s.timestamp).toLocaleString()} (${(s.size / 1024 / 1024).toFixed(2)}MB)`,
+        value: s.id
+      }))
+      choices.push(new inquirer.default.Separator(), { name: '← Cancel', value: 'cancel' })
+      const { snapshotId } = await inquirer.default.prompt([{
+        type: 'list',
+        name: 'snapshotId',
+        message: 'Select snapshot to restore:',
+        choices
+      }])
+      if (snapshotId === 'cancel') return
+      await this.e2eRestore(snapshotId)
+    } catch (error) {
+      Logger.error(`Failed to list snapshots: ${error.message}`)
+    }
+  }
+
+  async e2eCleanupInteractive () {
+    const snapshotManager = new SnapshotManager(this.config)
+    try {
+      const result = await snapshotManager.listSnapshots()
+      const snapshots = result.snapshots || []
+      if (snapshots.length === 0) {
+        console.log('\nNo snapshots found.\n')
+        return
+      }
+      const inquirer = await import('inquirer')
+      const choices = snapshots.map(s => ({
+        name: `${s.id} - ${new Date(s.timestamp).toLocaleString()} (${(s.size / 1024 / 1024).toFixed(2)}MB)`,
+        value: s.id
+      }))
+      choices.push(
+        new inquirer.default.Separator(),
+        { name: '🗑️  Delete ALL snapshots', value: 'all' },
+        { name: '← Cancel', value: 'cancel' }
+      )
+      const { snapshotId } = await inquirer.default.prompt([{
+        type: 'list',
+        name: 'snapshotId',
+        message: 'Select snapshot to delete:',
+        choices
+      }])
+      if (snapshotId === 'cancel') return
+      if (snapshotId === 'all') {
+        await this.e2eCleanup(null)
+      } else {
+        await this.e2eCleanup(snapshotId)
+      }
+    } catch (error) {
+      Logger.error(`Failed to cleanup: ${error.message}`)
+    }
+  }
+
+  async e2eRun (options = {}) {
+    const snapshotManager = new SnapshotManager(this.config)
+    const testCommand = this.config.e2e?.testCommand || 'npm run test:e2e'
+    const timeout = this.config.e2e?.timeout || 300000
+    const keepOnFailure = this.config.e2e?.keepSnapshotOnFailure !== false
+    const keepOnSuccess = this.config.e2e?.keepSnapshotOnSuccess === true
+    let snapshotId = null
+    let testsPassed = false
+    const spinner = Logger.spinner('Starting e2e test run')
+    try {
+      // Step 1: Create snapshot
+      spinner.text = 'Creating snapshot of development environment...'
+      const snapshotResult = await snapshotManager.createSnapshot()
+      const snapshotData = snapshotResult.data || snapshotResult
+      snapshotId = snapshotData.snapshotId
+      const servicesInfo = Object.keys(snapshotData.services || {}).map(s => {
+        const info = snapshotData.services[s]
+        if (info.database) return `${s} (${info.database})`
+        if (info.collections) return `${s} (${info.collections} collections, ${info.documents} docs)`
+        if (info.tables) return `${s} (${info.tables} tables, ${info.records} records)`
+        return s
+      }).join(', ')
+      spinner.succeed(`Snapshot created: ${snapshotId}`)
+      console.log(`  Services: ${servicesInfo}\n`)
+      // Step 2: Run tests
+      spinner.start('Running e2e tests...')
+      spinner.text = `Running: ${testCommand}`
+      try {
+        const testProcess = execa('sh', ['-c', testCommand], {
+          cwd: process.cwd(),
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout
+        })
+        // Stream output
+        testProcess.stdout.on('data', (data) => {
+          process.stdout.write(data)
+        })
+        testProcess.stderr.on('data', (data) => {
+          process.stderr.write(data)
+        })
+        await testProcess
+        testsPassed = true
+        spinner.succeed('Tests passed!')
+      } catch (error) {
+        spinner.fail('Tests failed')
+        testsPassed = false
+      }
+      // Step 3: Restore snapshot
+      spinner.start('Restoring snapshot...')
+      await snapshotManager.restoreSnapshot(snapshotId, true)
+      spinner.succeed('Environment restored to pre-test state')
+      // Step 4: Cleanup snapshot
+      const shouldKeep = (testsPassed && keepOnSuccess) || (!testsPassed && keepOnFailure) || options.keepSnapshot
+      if (shouldKeep) {
+        console.log(`\n📸 Snapshot kept: ${snapshotId}`)
+        console.log(`   To restore: goki-dev e2e restore ${snapshotId}`)
+        console.log(`   To cleanup: goki-dev e2e cleanup ${snapshotId}\n`)
+      } else {
+        spinner.start('Cleaning up snapshot...')
+        await snapshotManager.cleanupSnapshot(snapshotId)
+        spinner.succeed('Snapshot cleaned up')
+      }
+      // Summary
+      console.log('')
+      if (testsPassed) {
+        console.log('✅ E2E tests complete')
+        console.log('   Tests: ✓ Passed')
+      } else {
+        console.log('❌ E2E tests failed')
+        console.log('   Tests: ✗ Failed')
+      }
+      console.log('   Environment: ✓ Restored to pre-test state\n')
+      if (!testsPassed) {
+        process.exit(1)
+      }
+    } catch (error) {
+      spinner.fail('E2E test run failed')
+      Logger.error(error.message)
+      if (snapshotId) {
+        console.log(`\nSnapshot ID: ${snapshotId}`)
+        console.log(`To restore manually: goki-dev e2e restore ${snapshotId}\n`)
+      }
+      process.exit(1)
+    }
+  }
+
+  async e2eSnapshot () {
+    const snapshotManager = new SnapshotManager(this.config)
+    const spinner = Logger.spinner('Creating snapshot')
+    try {
+      const result = await snapshotManager.createSnapshot()
+      const snapshotData = result.data || result
+      spinner.succeed(`Snapshot created: ${snapshotData.snapshotId}`)
+      console.log('')
+      for (const [service, info] of Object.entries(snapshotData.services || {})) {
+        if (info.database) {
+          console.log(`  - PostgreSQL: ${info.database} (${(info.size / 1024 / 1024).toFixed(2)}MB)`)
+        } else if (info.collections !== undefined) {
+          console.log(`  - Firestore: ${info.collections} collections, ${info.documents} documents (${(info.size / 1024 / 1024).toFixed(2)}MB)`)
+        } else if (info.tables !== undefined) {
+          console.log(`  - SQLite: ${info.tables} tables, ${info.records} records (${(info.size / 1024).toFixed(2)}KB)`)
+        }
+      }
+      console.log('')
+      console.log(`To restore: goki-dev e2e restore ${snapshotData.snapshotId}`)
+      console.log('')
+    } catch (error) {
+      spinner.fail('Failed to create snapshot')
+      Logger.error(error.message)
+      process.exit(1)
+    }
+  }
+
+  async e2eRestore (snapshotId) {
+    const snapshotManager = new SnapshotManager(this.config)
+    try {
+      const inquirer = await import('inquirer')
+      const { confirm } = await inquirer.default.prompt([{
+        type: 'confirm',
+        name: 'confirm',
+        message: '⚠️  This will OVERWRITE current development data. Continue?',
+        default: false
+      }])
+      if (!confirm) {
+        Logger.info('Cancelled')
+        return
+      }
+      const spinner = Logger.spinner('Restoring snapshot')
+      await snapshotManager.restoreSnapshot(snapshotId, true)
+      spinner.succeed(`Restored snapshot: ${snapshotId}`)
+    } catch (error) {
+      Logger.error(`Failed to restore snapshot: ${error.message}`)
+      process.exit(1)
+    }
+  }
+
+  async e2eList () {
+    const snapshotManager = new SnapshotManager(this.config)
+    try {
+      const result = await snapshotManager.listSnapshots()
+      const resultData = result.data || result
+      const snapshots = resultData.snapshots || []
+      if (snapshots.length === 0) {
+        console.log('\nNo snapshots found.\n')
+        console.log('Create a snapshot with: goki-dev e2e snapshot\n')
+        return
+      }
+      console.log('\nAvailable snapshots:\n')
+      for (const snapshot of snapshots) {
+        const date = new Date(snapshot.timestamp).toLocaleString()
+        const size = (snapshot.size / 1024 / 1024).toFixed(2)
+        const services = snapshot.services.join(', ')
+        console.log(`  ${snapshot.id}  ${date}  ${size}MB  (${services})`)
+      }
+      console.log('')
+      console.log('To restore: goki-dev e2e restore <id>')
+      console.log('To cleanup: goki-dev e2e cleanup <id>\n')
+    } catch (error) {
+      Logger.error(`Failed to list snapshots: ${error.message}`)
+      process.exit(1)
+    }
+  }
+
+  async e2eCleanup (snapshotId = null) {
+    const snapshotManager = new SnapshotManager(this.config)
+    try {
+      const inquirer = await import('inquirer')
+      const message = snapshotId
+        ? `⚠️  This will DELETE snapshot "${snapshotId}". Continue?`
+        : '⚠️  This will DELETE ALL snapshots. Continue?'
+      const { confirm } = await inquirer.default.prompt([{
+        type: 'confirm',
+        name: 'confirm',
+        message,
+        default: false
+      }])
+      if (!confirm) {
+        Logger.info('Cancelled')
+        return
+      }
+      const spinner = Logger.spinner('Deleting snapshot(s)')
+      await snapshotManager.cleanupSnapshot(snapshotId)
+      if (snapshotId) {
+        spinner.succeed(`Snapshot deleted: ${snapshotId}`)
+      } else {
+        spinner.succeed('All snapshots deleted')
+      }
+    } catch (error) {
+      Logger.error(`Failed to delete snapshot: ${error.message}`)
+      process.exit(1)
+    }
+  }
+
+  async verifyServiceDependencies (spinner) {
+    const { services = [] } = this.config.dependencies || {}
+    if (services.length === 0) return
+    for (const dep of services) {
+      spinner.text = `Checking ${dep.name}...`
+      const isHealthy = await this.checkServiceHealth(dep.healthEndpoint)
+      if (!isHealthy) {
+        if (dep.required) {
+          if (dep.autoStart) {
+            const started = await this.tryAutoStartDependency(dep, spinner)
+            if (!started) {
+              spinner.fail(`${dep.name} is required but not running`)
+              Logger.error(dep.description || `${dep.name} is required for ${this.config.name}`)
+              process.exit(1)
+            }
+          } else {
+            spinner.fail(`${dep.name} is not running`)
+            Logger.error(dep.description || `${dep.name} is required for ${this.config.name}`)
+            Logger.info(`Start ${dep.name} first: cd ../${dep.name} && goki-dev start`)
+            process.exit(1)
+          }
+        } else {
+          spinner.warn(`${dep.name} is not healthy (optional dependency)`)
+        }
+      } else {
+        Logger.info(`✓ ${dep.name} is healthy`)
+      }
+    }
+  }
+
+  async checkServiceHealth (healthEndpoint) {
+    try {
+      const response = await fetch('http://localhost:9000/v1/services/health/check', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ healthEndpoint }),
+        signal: AbortSignal.timeout(10000)
+      })
+      if (!response.ok) return false
+      const result = await response.json()
+      return result.data?.healthy || false
+    } catch {
+      return false
+    }
+  }
+
+  async tryAutoStartDependency (dep, spinner) {
+    const depProject = await this.findDependencyProject(dep.name)
+    if (!depProject.found) {
+      Logger.warn(`Cannot find ${dep.name} at ${depProject.searchPath}`)
+      return false
+    }
+    if (dep.containerName) {
+      spinner.text = `Checking if ${dep.name} container is already running...`
+      const isRunning = await this.checkContainerRunning(dep.containerName)
+      if (isRunning) {
+        Logger.info(`✓ ${dep.name} container is already running`)
+        const isHealthy = await this.checkServiceHealth(dep.healthEndpoint)
+        if (isHealthy) {
+          Logger.info(`✓ ${dep.name} is healthy`)
+          return true
+        }
+        Logger.warn(`${dep.name} container is running but health check failed`)
+      }
+    }
+    spinner.stop()
+    const shouldStart = await this.promptStartDependency(dep.name, dep.description)
+    if (!shouldStart) {
+      return false
+    }
+    spinner.start(`Starting ${dep.name}...`)
+    try {
+      const { execSync } = await import('child_process')
+      execSync('goki-dev start', {
+        stdio: 'inherit',
+        cwd: depProject.path
+      })
+      spinner.text = `Waiting for ${dep.name} to be ready...`
+      for (let i = 0; i < 30; i++) {
+        const isHealthy = await this.checkServiceHealth(dep.healthEndpoint)
+        if (isHealthy) {
+          Logger.info(`✓ ${dep.name} started successfully`)
+          spinner.start()
+          return true
+        }
+        await new Promise(resolve => setTimeout(resolve, 1000))
+      }
+      Logger.warn(`${dep.name} started but health check timed out`)
+      return false
+    } catch (error) {
+      Logger.error(`Failed to start ${dep.name}: ${error.message}`)
+      return false
+    }
+  }
+
+  async checkContainerRunning (containerName) {
+    try {
+      const { execa } = await import('execa')
+      const { stdout } = await execa('docker', [
+        'inspect',
+        '--format={{.State.Running}}',
+        containerName
+      ])
+      return stdout.trim() === 'true'
+    } catch {
+      return false
+    }
+  }
+
+  async findDependencyProject (serviceName) {
+    const path = await import('path')
+    const fs = await import('fs')
+    const currentDir = process.cwd()
+    const parentDir = path.dirname(currentDir)
+    const depPath = path.join(parentDir, serviceName)
+    const configPath = path.join(depPath, '.dev-tools', 'config.js')
+    if (fs.existsSync(configPath)) {
+      return {
+        found: true,
+        path: depPath,
+        configPath
+      }
+    }
+    return {
+      found: false,
+      searchPath: depPath
+    }
+  }
+
+  async promptStartDependency (serviceName, description) {
+    const inquirer = (await import('inquirer')).default
+    const message = description
+      ? `${serviceName} is required (${description}). Start it now?`
+      : `${serviceName} is required. Start it now?`
+    const { shouldStart } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'shouldStart',
+        message,
+        default: true
+      }
+    ])
+    return shouldStart
+  }
+}