aidp 0.21.1 → 0.22.0

data/lib/aidp/setup/devcontainer/port_manager.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module Aidp
+  module Setup
+    module Devcontainer
+      # Manages port configuration for devcontainers and generates documentation
+      class PortManager
+        # Standard port assignments for common services
+        STANDARD_PORTS = {
+          web_app: {number: 3000, label: "Application", protocol: "http"},
+          remote_terminal: {number: 7681, label: "Remote Terminal (ttyd)", protocol: "http"},
+          playwright_debug: {number: 9222, label: "Playwright Debug", protocol: "http"},
+          mcp_server: {number: 8080, label: "MCP Server", protocol: "http"},
+          postgres: {number: 5432, label: "PostgreSQL", protocol: "tcp"},
+          redis: {number: 6379, label: "Redis", protocol: "tcp"},
+          mysql: {number: 3306, label: "MySQL", protocol: "tcp"}
+        }.freeze
+
+        def initialize(wizard_config)
+          @wizard_config = wizard_config
+          @detected_ports = []
+        end
+
+        # Detect all required ports based on wizard configuration
+        # @return [Array<Hash>] Array of port configurations
+        def detect_required_ports
+          return @detected_ports if @detected_ports.any?
+
+          @detected_ports = []
+
+          detect_application_ports
+          detect_tool_ports
+          detect_service_ports
+          add_custom_ports
+
+          Aidp.log_debug("port_manager", "detected ports",
+            count: @detected_ports.size,
+            ports: @detected_ports.map { |p| p[:number] })
+
+          @detected_ports
+        end
+
+        # Generate forwardPorts array for devcontainer.json
+        # @return [Array<Integer>] Port numbers
+        def generate_forward_ports
+          detect_required_ports.map { |p| p[:number] }
+        end
+
+        # Generate portsAttributes hash for devcontainer.json
+        # @return [Hash] Port attributes with labels and settings
+        def generate_port_attributes
+          detect_required_ports.each_with_object({}) do |port, attrs|
+            attrs[port[:number].to_s] = {
+              "label" => port[:label],
+              "protocol" => port[:protocol] || "http",
+              "onAutoForward" => port[:auto_open] ? "notify" : "silent"
+            }
+          end
+        end
+
+        # Generate PORTS.md documentation
+        # @param output_path [String] Path to write PORTS.md
+        # @return [String] Generated markdown content
+        def generate_ports_documentation(output_path = nil)
+          detect_required_ports
+
+          content = build_ports_markdown
+          File.write(output_path, content) if output_path
+
+          content
+        end
+
+        private
+
+        def detect_application_ports
+          # Web application port
+          if web_application?
+            @detected_ports << {
+              number: @wizard_config[:app_port] || 3000,
+              label: @wizard_config[:app_label] || "Application",
+              protocol: "http",
+              auto_open: true,
+              description: "Main application web server"
+            }
+          end
+
+          # API server (if separate from main app)
+          if @wizard_config[:api_port]
+            @detected_ports << {
+              number: @wizard_config[:api_port],
+              label: "API Server",
+              protocol: "http",
+              auto_open: false,
+              description: "REST/GraphQL API endpoint"
+            }
+          end
+        end
+
+        def detect_tool_ports
+          # Watch mode remote terminal
+          if @wizard_config[:watch_mode] || @wizard_config[:enable_watch]
+            @detected_ports << STANDARD_PORTS[:remote_terminal].merge(
+              auto_open: false,
+              description: "Terminal access via ttyd for watch mode operations"
+            )
+          end
+
+          # Playwright debug port
+          if playwright_enabled?
+            @detected_ports << STANDARD_PORTS[:playwright_debug].merge(
+              auto_open: false,
+              description: "Chrome DevTools Protocol for Playwright debugging"
+            )
+          end
+
+          # MCP server
+          if mcp_enabled?
+            port_config = STANDARD_PORTS[:mcp_server].dup
+            port_config[:number] = @wizard_config[:mcp_port] if @wizard_config[:mcp_port]
+            @detected_ports << port_config.merge(
+              auto_open: false,
+              description: "Model Context Protocol server endpoint"
+            )
+          end
+        end
+
+        def detect_service_ports
+          return unless @wizard_config[:services]
+
+          @wizard_config[:services].each do |service|
+            service_key = service.to_sym
+            next unless STANDARD_PORTS.key?(service_key)
+
+            @detected_ports << STANDARD_PORTS[service_key].merge(
+              auto_open: false,
+              description: service_description(service_key)
+            )
+          end
+        end
+
+        def add_custom_ports
+          return unless @wizard_config[:custom_ports]
+
+          @wizard_config[:custom_ports].each do |port|
+            port_config = if port.is_a?(Hash)
+              {
+                number: port[:number],
+                label: port[:label] || "Custom Port",
+                protocol: port[:protocol] || "http",
+                auto_open: port[:auto_open] || false,
+                description: port[:description] || "User-defined port"
+              }
+            else
+              {
+                number: port.to_i,
+                label: "Custom Port",
+                protocol: "http",
+                auto_open: false,
+                description: "User-defined port"
+              }
+            end
+
+            @detected_ports << port_config if port_config[:number]&.positive?
+          end
+        end
+
+        def build_ports_markdown
+          <<~MARKDOWN
+            # Port Configuration
+
+            This document lists all ports configured for this development environment.
+
+            ## Overview
+
+            Total ports configured: **#{@detected_ports.size}**
+
+            ## Port Details
+
+            #{build_port_table}
+
+            ## Security Considerations
+
+            - All ports are forwarded from the devcontainer to your local machine
+            - Ports marked as "Auto-open" will trigger a notification when the container starts
+            - Ensure sensitive services (databases, etc.) are not exposed publicly
+            - Use firewall rules to restrict access if deploying to a remote environment
+
+            ## Adding Custom Ports
+
+            To add custom ports, update your `aidp.yml`:
+
+            ```yaml
+            devcontainer:
+              custom_ports:
+                - number: 8000
+                  label: "Custom Service"
+                  protocol: "http"
+                  auto_open: false
+            ```
+
+            Then re-run `aidp config --interactive` to update your devcontainer.
+
+            ## Firewall Configuration
+
+            #{build_firewall_section}
+
+            ---
+
+            *Generated by AIDP #{Aidp::VERSION} on #{Time.now.utc.strftime("%Y-%m-%d")}*
+          MARKDOWN
+        end
+
+        def build_port_table
+          return "*No ports configured*" if @detected_ports.empty?
+
+          table = "| Port | Label | Protocol | Auto-open | Description |\n"
+          table += "|------|-------|----------|-----------|-------------|\n"
+
+          @detected_ports.sort_by { |p| p[:number] }.each do |port|
+            auto_open = port[:auto_open] ? "Yes" : "No"
+            table += "| #{port[:number]} | #{port[:label]} | #{port[:protocol]} | #{auto_open} | #{port[:description] || "-"} |\n"
+          end
+
+          table
+        end
+
+        def build_firewall_section
+          if @detected_ports.empty?
+            return "No ports require firewall configuration."
+          end
+
+          ports_list = @detected_ports.map { |p| p[:number] }.sort.join(", ")
+
+          <<~FIREWALL
+            If running in a cloud environment or VM, ensure these ports are allowed through your firewall:
+
+            ```bash
+            # Example: UFW (Ubuntu)
+            #{@detected_ports.sort_by { |p| p[:number] }.map { |p| "sudo ufw allow #{p[:number]}/tcp  # #{p[:label]}" }.join("\n")}
+
+            # Example: firewalld (RHEL/CentOS)
+            #{@detected_ports.sort_by { |p| p[:number] }.map { |p| "sudo firewall-cmd --permanent --add-port=#{p[:number]}/tcp  # #{p[:label]}" }.join("\n")}
+            sudo firewall-cmd --reload
+            ```
+
+            **Ports to allow:** #{ports_list}
+          FIREWALL
+        end
+
+        def web_application?
+          @wizard_config[:app_type]&.match?(/web|rails|sinatra|express|django|flask/) ||
+            @wizard_config[:has_web_interface] == true
+        end
+
+        def playwright_enabled?
+          @wizard_config[:interactive_tools]&.include?("playwright") ||
+            @wizard_config[:test_framework]&.include?("playwright")
+        end
+
+        def mcp_enabled?
+          @wizard_config[:interactive_tools]&.include?("mcp") ||
+            @wizard_config[:enable_mcp] == true
+        end
+
+        def service_description(service_key)
+          case service_key
+          when :postgres
+            "PostgreSQL database server"
+          when :redis
+            "Redis in-memory data store"
+          when :mysql
+            "MySQL database server"
+          when :remote_terminal
+            "Remote terminal access"
+          when :playwright_debug
+            "Browser automation debugging"
+          when :mcp_server
+            "Model Context Protocol server"
+          else
+            "Service port"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aidp/setup/wizard.rb

@@ -4,9 +4,14 @@ require "tty-prompt"
 require "yaml"
 require "time"
 require "fileutils"
+require "json"
 
 require_relative "../util"
 require_relative "../config/paths"
+require_relative "devcontainer/parser"
+require_relative "devcontainer/generator"
+require_relative "devcontainer/port_manager"
+require_relative "devcontainer/backup_manager"
 
 module Aidp
   module Setup
@@ -15,6 +20,7 @@ module Aidp
     # while remaining idempotent and safe to re-run.
     class Wizard
       SCHEMA_VERSION = 1
+      DEVCONTAINER_COMPONENT = "setup_wizard.devcontainer"
 
       attr_reader :project_dir, :prompt, :dry_run
 
@@ -41,6 +47,7 @@ module Aidp
         configure_nfrs
         configure_logging
         configure_modes
+        configure_devcontainer
 
         yaml_content = generate_yaml
         display_preview(yaml_content)
@@ -852,6 +859,9 @@ module Aidp
       def save_config(yaml_content)
         Aidp::ConfigPaths.ensure_config_dir(project_dir)
         File.write(config_path, yaml_content)
+
+        # Generate devcontainer if managed
+        generate_devcontainer_file
       end
 
       def display_warnings
@@ -1291,6 +1301,141 @@ module Aidp
       def project_file?(relative_path)
         File.exist?(File.join(project_dir, relative_path))
       end
+
+      def configure_devcontainer
+        prompt.say("\n🐳 Devcontainer Configuration")
+        Aidp.log_debug(DEVCONTAINER_COMPONENT, "configure.start")
+
+        # Detect existing devcontainer
+        parser = Devcontainer::Parser.new(project_dir)
+        existing_devcontainer = parser.devcontainer_exists? ? parser.parse : nil
+
+        if existing_devcontainer
+          prompt.say("✓ Found existing devcontainer.json")
+          Aidp.log_debug(DEVCONTAINER_COMPONENT, "configure.detected_existing",
+            path: parser.detect)
+        end
+
+        # Ask if user wants AIDP to manage devcontainer
+        manage = prompt.yes?(
+          "Would you like AIDP to manage your devcontainer configuration?",
+          default: (@config.dig(:devcontainer, :manage) || existing_devcontainer) ? true : false
+        )
+
+        unless manage
+          Aidp.log_debug(DEVCONTAINER_COMPONENT, "configure.opt_out")
+          return set([:devcontainer, :manage], false)
+        end
+
+        # Build wizard config and detect ports
+        wizard_config = build_wizard_config_for_devcontainer
+        port_manager = Devcontainer::PortManager.new(wizard_config)
+        detected_ports = port_manager.detect_required_ports
+
+        # Show detected ports
+        if detected_ports.any?
+          prompt.say("\nDetected ports:")
+          detected_ports.each do |port|
+            prompt.say("  • #{port[:number]} - #{port[:label]}")
+          end
+          Aidp.log_debug(DEVCONTAINER_COMPONENT, "configure.detected_ports",
+            ports: detected_ports.map { |port| port[:number] })
+        end
+
+        # Ask about custom ports
+        custom_ports = []
+        if prompt.yes?("Add custom ports?", default: false)
+          loop do
+            port_num = prompt.ask("Port number (or press Enter to finish):")
+            break if port_num.nil? || port_num.to_s.strip.empty?
+
+            unless port_num.to_s.match?(/^\d+$/)
+              prompt.error("Port must be a number")
+              next
+            end
+
+            port_label = prompt.ask("Port label:", default: "Custom")
+            custom_ports << {number: port_num.to_i, label: port_label}
+          end
+          Aidp.log_debug(DEVCONTAINER_COMPONENT, "configure.custom_ports_selected",
+            ports: custom_ports.map { |port| port[:number] })
+        end
+
+        # Save configuration
+        set([:devcontainer, :manage], true)
+        set([:devcontainer, :custom_ports], custom_ports) if custom_ports.any?
+        set([:devcontainer, :last_generated], Time.now.utc.iso8601)
+        Aidp.log_debug(DEVCONTAINER_COMPONENT, "configure.enabled",
+          custom_port_count: custom_ports.count,
+          detected_port_count: detected_ports.count)
+      end
+
+      def build_wizard_config_for_devcontainer
+        {
+          providers: @config[:providers]&.keys,
+          test_framework: @config.dig(:work_loop, :test_commands)&.first&.dig(:framework),
+          linters: @config.dig(:work_loop, :linting, :tools),
+          watch_mode: @config.dig(:work_loop, :watch, :enabled),
+          app_type: detect_app_type,
+          services: detect_services,
+          custom_ports: @config.dig(:devcontainer, :custom_ports)
+        }.compact
+      end
+
+      def detect_app_type
+        return "rails_web" if project_file?("config/routes.rb")
+        return "sinatra" if project_file?("config.ru")
+        return "express" if project_file?("app.js") && project_file?("package.json")
+        "cli"
+      end
+
+      def detect_services
+        services = []
+        services << "postgres" if project_file?("config/database.yml")
+        services << "redis" if project_file?("config/redis.yml")
+        services
+      end
+
+      def generate_devcontainer_file
+        unless @config.dig(:devcontainer, :manage)
+          Aidp.log_debug(DEVCONTAINER_COMPONENT, "generate.skip_unmanaged")
+          return
+        end
+
+        Aidp.log_debug(DEVCONTAINER_COMPONENT, "generate.start")
+
+        wizard_config = build_wizard_config_for_devcontainer
+        Aidp.log_debug(DEVCONTAINER_COMPONENT, "generate.wizard_config",
+          keys: wizard_config.keys)
+
+        parser = Devcontainer::Parser.new(project_dir)
+        existing = parser.devcontainer_exists? ? parser.parse : nil
+
+        generator = Devcontainer::Generator.new(project_dir, @config)
+        new_config = generator.generate(wizard_config, existing)
+
+        # Create backup if existing file
+        if existing
+          backup_manager = Devcontainer::BackupManager.new(project_dir)
+          backup_manager.create_backup(
+            parser.detect,
+            {reason: "wizard_update", timestamp: Time.now.utc.iso8601}
+          )
+          prompt.say("  └─ Backup created")
+          Aidp.log_debug(DEVCONTAINER_COMPONENT, "generate.backup_created",
+            path: parser.detect)
+        end
+
+        # Write devcontainer.json
+        devcontainer_path = File.join(project_dir, ".devcontainer", "devcontainer.json")
+        FileUtils.mkdir_p(File.dirname(devcontainer_path))
+        File.write(devcontainer_path, JSON.pretty_generate(new_config))
+
+        prompt.ok("✅ Generated #{devcontainer_path}")
+        Aidp.log_debug(DEVCONTAINER_COMPONENT, "generate.complete",
+          devcontainer_path: devcontainer_path,
+          forward_ports: new_config["forwardPorts"]&.length)
+      end
     end
   end
 end

data/lib/aidp/storage/csv_storage.rb

@@ -11,7 +11,7 @@ module Aidp
       include Aidp::RescueLogging
 
       def initialize(base_dir = ".aidp")
-        @base_dir = base_dir
+        @base_dir = sanitize_base_dir(base_dir)
         ensure_directory_exists
       end
 
@@ -191,7 +191,44 @@ module Aidp
       end
 
       def ensure_directory_exists
-        FileUtils.mkdir_p(@base_dir) unless Dir.exist?(@base_dir)
+        return if Dir.exist?(@base_dir)
+        begin
+          FileUtils.mkdir_p(@base_dir)
+        rescue SystemCallError => e
+          fallback = begin
+            home = Dir.respond_to?(:home) ? Dir.home : nil
+            if home && !home.empty? && File.writable?(home)
+              File.join(home, ".aidp")
+            else
+              File.join(Dir.tmpdir, "aidp_storage")
+            end
+          rescue
+            File.join(Dir.tmpdir, "aidp_storage")
+          end
+          Kernel.warn "[AIDP Storage] Cannot create base directory #{@base_dir}: #{e.class}: #{e.message}. Using fallback #{fallback}"
+          @base_dir = fallback
+          begin
+            FileUtils.mkdir_p(@base_dir) unless Dir.exist?(@base_dir)
+          rescue SystemCallError => e2
+            Kernel.warn "[AIDP Storage] Fallback directory creation also failed: #{e2.class}: #{e2.message}. Continuing without persistent CSV storage."
+          end
+        end
+      end
+
+      def sanitize_base_dir(dir)
+        return Dir.pwd if dir.nil? || dir.to_s.strip.empty?
+        str = dir.to_s
+        if str == File::SEPARATOR
+          fallback = begin
+            home = Dir.home
+            (home && !home.empty? && File.writable?(home)) ? File.join(home, ".aidp") : File.join(Dir.tmpdir, "aidp_storage")
+          rescue
+            File.join(Dir.tmpdir, "aidp_storage")
+          end
+          Kernel.warn "[AIDP Storage] Root base_dir detected - using fallback #{fallback} instead of '#{str}'"
+          return fallback
+        end
+        str
       end
     end
   end

data/lib/aidp/storage/file_manager.rb

@@ -8,9 +8,16 @@ module Aidp
     # Simple file manager that provides easy access to JSON and CSV storage
     class FileManager
       def initialize(base_dir = ".aidp")
-        @base_dir = base_dir
-        @json_storage = JsonStorage.new(base_dir)
-        @csv_storage = CsvStorage.new(base_dir)
+        @base_dir = sanitize_base_dir(base_dir)
+        @json_storage = JsonStorage.new(@base_dir)
+        @csv_storage = CsvStorage.new(@base_dir)
+        # Normalize base_dir if storages had to fallback
+        json_dir = @json_storage.instance_variable_get(:@base_dir)
+        csv_dir = @csv_storage.instance_variable_get(:@base_dir)
+        if json_dir != @base_dir || csv_dir != @base_dir
+          @base_dir = json_dir # Prefer JSON storage directory
+          Kernel.warn "[AIDP Storage] Base directory normalized to #{@base_dir} after fallback."
+        end
       end
 
       # JSON operations for structured data
@@ -209,6 +216,24 @@ module Aidp
       rescue => error
         {success: false, error: error.message}
       end
+
+      private
+
+      def sanitize_base_dir(dir)
+        return Dir.pwd if dir.nil? || dir.to_s.strip.empty?
+        str = dir.to_s
+        if str == File::SEPARATOR
+          fallback = begin
+            home = Dir.home
+            (home && !home.empty? && File.writable?(home)) ? File.join(home, ".aidp") : File.join(Dir.tmpdir, "aidp_storage")
+          rescue
+            File.join(Dir.tmpdir, "aidp_storage")
+          end
+          Kernel.warn "[AIDP Storage] Root base_dir detected - using fallback #{fallback} instead of '#{str}'"
+          return fallback
+        end
+        str
+      end
     end
   end
 end

data/lib/aidp/storage/json_storage.rb

@@ -11,7 +11,7 @@ module Aidp
       include Aidp::RescueLogging
 
       def initialize(base_dir = ".aidp")
-        @base_dir = base_dir
+        @base_dir = sanitize_base_dir(base_dir)
         ensure_directory_exists
       end
 
@@ -156,7 +156,46 @@ module Aidp
       end
 
       def ensure_directory_exists
-        FileUtils.mkdir_p(@base_dir) unless Dir.exist?(@base_dir)
+        return if Dir.exist?(@base_dir)
+        begin
+          FileUtils.mkdir_p(@base_dir)
+        rescue SystemCallError => e
+          # Fallback when directory creation fails (e.g., attempting to write to '/.aidp')
+          fallback = begin
+            home = Dir.respond_to?(:home) ? Dir.home : nil
+            if home && !home.empty? && File.writable?(home)
+              File.join(home, ".aidp")
+            else
+              File.join(Dir.tmpdir, "aidp_storage")
+            end
+          rescue
+            File.join(Dir.tmpdir, "aidp_storage")
+          end
+          Kernel.warn "[AIDP Storage] Cannot create base directory #{@base_dir}: #{e.class}: #{e.message}. Using fallback #{fallback}"
+          @base_dir = fallback
+          begin
+            FileUtils.mkdir_p(@base_dir) unless Dir.exist?(@base_dir)
+          rescue SystemCallError => e2
+            Kernel.warn "[AIDP Storage] Fallback directory creation also failed: #{e2.class}: #{e2.message}. Continuing without persistent JSON storage."
+          end
+        end
+      end
+
+      def sanitize_base_dir(dir)
+        return Dir.pwd if dir.nil? || dir.to_s.strip.empty?
+        str = dir.to_s
+        # If given root '/', redirect to a writable location to avoid EACCES on CI
+        if str == File::SEPARATOR
+          fallback = begin
+            home = Dir.home
+            (home && !home.empty? && File.writable?(home)) ? File.join(home, ".aidp") : File.join(Dir.tmpdir, "aidp_storage")
+          rescue
+            File.join(Dir.tmpdir, "aidp_storage")
+          end
+          Kernel.warn "[AIDP Storage] Root base_dir detected - using fallback #{fallback} instead of '#{str}'"
+          return fallback
+        end
+        str
       end
     end
   end

data/lib/aidp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Aidp
-  VERSION = "0.21.1"
+  VERSION = "0.22.0"
 end