aidp 0.34.0 → 0.39.3

data/lib/aidp/init/agent_instructions_generator.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+
+module Aidp
+  module Init
+    # Generates agent instruction files for AI coding assistants.
+    #
+    # This generator creates a master AGENTS.md file and symlinks it to
+    # provider-specific locations (e.g., CLAUDE.md, .github/copilot-instructions.md).
+    #
+    # @example Basic usage
+    #   generator = AgentInstructionsGenerator.new(project_dir: "/path/to/project")
+    #   files = generator.generate(analysis: analysis, preferences: preferences)
+    #
+    class AgentInstructionsGenerator
+      include Aidp::MessageDisplay
+
+      MASTER_FILE = "AGENTS.md"
+
+      # Known provider classes for instruction file generation
+      PROVIDER_CLASSES = %w[
+        Anthropic
+        GithubCopilot
+        Cursor
+        Gemini
+        Aider
+        Kilocode
+        Opencode
+        Codex
+      ].freeze
+
+      def initialize(project_dir = Dir.pwd, prompt: nil)
+        @project_dir = project_dir
+        @prompt = prompt
+      end
+
+      # Generate agent instruction files
+      #
+      # @param analysis [Hash] Project analysis results
+      # @param preferences [Hash] User preferences
+      # @return [Array<String>] List of generated files
+      def generate(analysis:, preferences: {})
+        Aidp.log_debug("agent_instructions_generator", "starting_generation",
+          project_dir: @project_dir)
+
+        generated_files = []
+        skipped_files = []
+        symlinked_files = []
+
+        # Generate master AGENTS.md
+        master_path = File.join(@project_dir, MASTER_FILE)
+        if generate_master_file(master_path, analysis, preferences)
+          generated_files << MASTER_FILE
+        end
+
+        # Create symlinks to provider-specific locations
+        provider_instruction_files.each do |file_info|
+          result = create_provider_symlink(file_info, master_path)
+          case result[:status]
+          when :created
+            symlinked_files << file_info[:path]
+          when :skipped
+            skipped_files << {path: file_info[:path], reason: result[:reason]}
+          end
+        end
+
+        # Report results
+        report_generation_results(generated_files, symlinked_files, skipped_files)
+
+        generated_files + symlinked_files
+      end
+
+      # Check if master AGENTS.md exists
+      #
+      # @return [Boolean]
+      def exists?
+        File.exist?(File.join(@project_dir, MASTER_FILE))
+      end
+
+      # Get all provider instruction file paths
+      #
+      # @return [Array<Hash>] Array of file info hashes
+      def provider_instruction_files
+        @provider_instruction_files ||= collect_provider_instruction_files
+      end
+
+      # Preview what files would be generated
+      #
+      # @return [Hash] Preview information
+      def preview
+        existing = []
+        to_create = []
+        to_symlink = []
+
+        master_path = File.join(@project_dir, MASTER_FILE)
+        if File.exist?(master_path)
+          existing << MASTER_FILE
+        else
+          to_create << MASTER_FILE
+        end
+
+        provider_instruction_files.each do |file_info|
+          full_path = File.join(@project_dir, file_info[:path])
+          if File.exist?(full_path) || File.symlink?(full_path)
+            existing << file_info[:path]
+          else
+            to_symlink << file_info[:path]
+          end
+        end
+
+        {
+          existing: existing,
+          to_create: to_create,
+          to_symlink: to_symlink
+        }
+      end
+
+      private
+
+      def collect_provider_instruction_files
+        files = []
+
+        PROVIDER_CLASSES.each do |class_name|
+          provider_class = AgentHarness::Providers.const_get(class_name)
+          next unless provider_class.respond_to?(:instruction_file_paths)
+
+          provider_class.instruction_file_paths.each do |file_info|
+            files << file_info.merge(provider: class_name.downcase)
+          end
+        rescue NameError => e
+          Aidp.log_debug("agent_instructions_generator", "provider_not_found",
+            provider: class_name, error: e.message)
+        end
+
+        files
+      end
+
+      def generate_master_file(path, analysis, preferences)
+        if File.exist?(path)
+          Aidp.log_debug("agent_instructions_generator", "master_exists",
+            path: path)
+          return false
+        end
+
+        content = build_master_content(analysis, preferences)
+        File.write(path, content)
+
+        Aidp.log_debug("agent_instructions_generator", "master_created",
+          path: path, size: content.length)
+        true
+      end
+
+      def build_master_content(analysis, preferences)
+        languages = format_list(analysis[:languages]&.keys)
+        frameworks = extract_confident_names(analysis[:frameworks], threshold: 0.7)
+        test_frameworks = extract_confident_names(analysis[:test_frameworks], threshold: 0.7)
+
+        <<~AGENTS
+          # AI Agent Instructions
+
+          > Generated by `aidp init` on #{Time.now.utc.iso8601}
+          >
+          > This file provides instructions for AI coding assistants working on this project.
+          > Provider-specific instruction files (CLAUDE.md, .github/copilot-instructions.md, etc.)
+          > are symlinked to this master file for consistency.
+
+          ## Primary Reference
+
+          **Before making ANY code changes, read and follow [`docs/LLM_STYLE_GUIDE.md`](docs/LLM_STYLE_GUIDE.md).**
+
+          The LLM_STYLE_GUIDE is your primary reference for all coding standards and patterns.
+
+          ## Project Overview
+
+          #{build_project_overview(analysis)}
+
+          ## Key Principles
+
+          1. **Follow the LLM_STYLE_GUIDE** - All code must adhere to the documented standards
+          2. **Read before writing** - Always read existing code before making modifications
+          3. **Test at boundaries** - Mock only external services (network, filesystem, APIs)
+          4. **Log extensively** - Use `Aidp.log_debug()` for important code paths
+          5. **Small, focused changes** - Follow Sandi Metz guidelines for code organization
+
+          ## Quick Reference
+
+          ### Languages & Frameworks
+          - **Languages**: #{languages.empty? ? "Not detected" : languages}
+          - **Frameworks**: #{frameworks.empty? ? "None detected" : frameworks.join(", ")}
+          - **Testing**: #{test_frameworks.empty? ? "Unknown" : test_frameworks.join(", ")}
+
+          ### Important Documentation
+          - [`docs/LLM_STYLE_GUIDE.md`](docs/LLM_STYLE_GUIDE.md) - Coding standards (PRIMARY)
+          - [`docs/PROJECT_ANALYSIS.md`](docs/PROJECT_ANALYSIS.md) - Project structure analysis
+          - [`docs/CODE_QUALITY_PLAN.md`](docs/CODE_QUALITY_PLAN.md) - Quality improvement plan
+
+          ## Anti-Patterns to Avoid
+
+          - Do NOT use `puts` or `print` for output (use TTY components)
+          - Do NOT add mock methods to production code (use dependency injection)
+          - Do NOT skip tests for "small fixes"
+          - Do NOT create god classes or methods
+          - Do NOT use regex for semantic analysis (use AI decision engines)
+
+          ## Getting Help
+
+          If uncertain about standards or patterns:
+          1. Check `docs/LLM_STYLE_GUIDE.md` first
+          2. Look at similar existing code in the project
+          3. Ask for clarification rather than guessing
+
+          ---
+
+          *This file is the single source of truth for AI agent instructions.*
+          *Provider-specific files are symlinked to this master file.*
+        AGENTS
+      end
+
+      def build_project_overview(analysis)
+        repo_stats = analysis[:repo_stats] || {}
+        lines = []
+
+        if repo_stats[:total_files]
+          lines << "- **Files**: #{repo_stats[:total_files]} total"
+        end
+
+        if analysis[:key_directories]&.any?
+          lines << "- **Key directories**: #{analysis[:key_directories].take(5).join(", ")}"
+        end
+
+        if repo_stats[:has_ci_config]
+          lines << "- **CI/CD**: Configured"
+        end
+
+        if repo_stats[:has_containerization]
+          lines << "- **Containerization**: Available"
+        end
+
+        if lines.empty?
+          "Project structure information not available. Run `aidp init --explain-detection` for details."
+        else
+          lines.join("\n")
+        end
+      end
+
+      def create_provider_symlink(file_info, master_path)
+        target_path = File.join(@project_dir, file_info[:path])
+
+        # Check if file already exists
+        if File.exist?(target_path) || File.symlink?(target_path)
+          Aidp.log_debug("agent_instructions_generator", "file_exists",
+            path: file_info[:path])
+          return {status: :skipped, reason: "file already exists"}
+        end
+
+        # Create parent directory if needed
+        parent_dir = File.dirname(target_path)
+        unless File.directory?(parent_dir)
+          FileUtils.mkdir_p(parent_dir)
+          Aidp.log_debug("agent_instructions_generator", "created_directory",
+            path: parent_dir)
+        end
+
+        # Calculate relative path from target to master
+        relative_master = calculate_relative_path(target_path, master_path)
+
+        # Create symlink
+        begin
+          File.symlink(relative_master, target_path)
+          Aidp.log_debug("agent_instructions_generator", "symlink_created",
+            target: file_info[:path], source: relative_master)
+          {status: :created}
+        rescue Errno::EEXIST
+          {status: :skipped, reason: "symlink already exists"}
+        rescue => e
+          Aidp.log_error("agent_instructions_generator", "symlink_failed",
+            target: file_info[:path], error: e.message)
+          {status: :skipped, reason: e.message}
+        end
+      end
+
+      def calculate_relative_path(from_path, to_path)
+        from_dir = File.dirname(from_path)
+        Pathname.new(to_path).relative_path_from(Pathname.new(from_dir)).to_s
+      end
+
+      def report_generation_results(generated, symlinked, skipped)
+        if generated.any?
+          display_message("\n   Created master agent instructions:", type: :info)
+          generated.each { |f| display_message("     - #{f}", type: :success) }
+        end
+
+        if symlinked.any?
+          display_message("\n   Created provider symlinks:", type: :info)
+          symlinked.each { |f| display_message("     - #{f} -> #{MASTER_FILE}", type: :success) }
+        end
+
+        if skipped.any?
+          display_message("\n   Preserved existing files:", type: :info)
+          skipped.each { |s| display_message("     - #{s[:path]} (#{s[:reason]})", type: :info) }
+        end
+      end
+
+      def format_list(values)
+        Array(values).join(", ")
+      end
+
+      def extract_confident_names(detections, threshold: 0.7, key: :name)
+        return [] if detections.nil? || detections.empty?
+
+        detections.select { |d| d[:confidence] >= threshold }.map { |d| d[key] }
+      end
+    end
+  end
+end

data/lib/aidp/init/runner.rb

@@ -5,6 +5,7 @@ require_relative "../message_display"
 require_relative "project_analyzer"
 require_relative "doc_generator"
 require_relative "devcontainer_generator"
+require_relative "agent_instructions_generator"
 
 module Aidp
   module Init
@@ -13,12 +14,13 @@ module Aidp
     class Runner
       include Aidp::MessageDisplay
 
-      def initialize(project_dir = Dir.pwd, prompt: TTY::Prompt.new, analyzer: nil, doc_generator: nil, devcontainer_generator: nil, options: {})
+      def initialize(project_dir = Dir.pwd, prompt: TTY::Prompt.new, analyzer: nil, doc_generator: nil, devcontainer_generator: nil, agent_instructions_generator: nil, options: {})
         @project_dir = project_dir
         @prompt = prompt
         @analyzer = analyzer || ProjectAnalyzer.new(project_dir)
         @doc_generator = doc_generator || DocGenerator.new(project_dir)
         @devcontainer_generator = devcontainer_generator || DevcontainerGenerator.new(project_dir)
+        @agent_instructions_generator = agent_instructions_generator || AgentInstructionsGenerator.new(project_dir, prompt: prompt)
         @options = options
       end
 
@@ -78,11 +80,17 @@ module Aidp
           devcontainer_files = @devcontainer_generator.generate(analysis: analysis, preferences: preferences)
           generated_files.concat(devcontainer_files)
 
-          display_message("\n📦 Generated devcontainer:", type: :info)
-          devcontainer_files.each { |file| display_message("  - #{file}", type: :success) }
+          display_message("\n   Generated devcontainer:", type: :info)
+          devcontainer_files.each { |file| display_message("     - #{file}", type: :success) }
         end
 
-        display_message("\n✅ aidp init complete.", type: :success)
+        # Generate agent instruction files
+        if @options[:with_agent_instructions] || should_generate_agent_instructions?(preferences)
+          agent_files = @agent_instructions_generator.generate(analysis: analysis, preferences: preferences)
+          generated_files.concat(agent_files)
+        end
+
+        display_message("\n   aidp init complete.", type: :success)
 
         {
           analysis: analysis,
@@ -264,6 +272,15 @@ module Aidp
           )
         end
 
+        # Ask about agent instruction files unless explicitly set via options
+        unless @options.key?(:with_agent_instructions)
+          prefs[:generate_agent_instructions] = ask_yes_no_with_context(
+            "Generate agent instruction files for AI coding assistants?",
+            context: "Creates AGENTS.md and symlinks to provider-specific locations (CLAUDE.md, .github/copilot-instructions.md, etc.).",
+            default: !@agent_instructions_generator.exists?
+          )
+        end
+
         prefs
       end
 
@@ -271,6 +288,10 @@ module Aidp
         preferences[:generate_devcontainer] == true
       end
 
+      def should_generate_agent_instructions?(preferences)
+        preferences[:generate_agent_instructions] == true
+      end
+
       def ask_yes_no_with_context(question, context:, default:)
         display_message("\n#{question}", type: :info)
         display_message("  ℹ️  #{context}", type: :info)

data/lib/aidp/interfaces/activity_monitor_interface.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module Aidp
+  module Interfaces
+    # ActivityMonitorInterface defines the contract for activity monitoring implementations.
+    # Activity monitoring tracks the state of long-running provider operations, detecting
+    # stuck processes and enabling timeout/cancellation logic.
+    #
+    # States:
+    # - :idle - No operation in progress
+    # - :working - Active and producing output
+    # - :stuck - No activity detected for stuck_timeout seconds
+    # - :completed - Operation finished successfully
+    # - :failed - Operation failed with an error
+    #
+    # @example Implementing the interface
+    #   class MyActivityMonitor
+    #     include Aidp::Interfaces::ActivityMonitorInterface
+    #
+    #     def start(step_name:, stuck_timeout:, on_state_change: nil)
+    #       # Implementation
+    #     end
+    #     # ... other methods
+    #   end
+    #
+    # @example Using an activity monitor
+    #   monitor = ActivityMonitor.new
+    #   monitor.start(step_name: "sending_prompt", stuck_timeout: 60)
+    #   monitor.record_activity("Received response")
+    #   monitor.complete
+    #
+    module ActivityMonitorInterface
+      # Valid activity states
+      STATES = [:idle, :working, :stuck, :completed, :failed].freeze
+
+      # Start monitoring an operation.
+      #
+      # @param step_name [String] name of the operation being monitored
+      # @param stuck_timeout [Integer] seconds before considering the operation stuck
+      # @param on_state_change [Proc, nil] callback for state changes (state, message)
+      # @return [void]
+      def start(step_name:, stuck_timeout:, on_state_change: nil)
+        raise NotImplementedError, "#{self.class} must implement #start"
+      end
+
+      # Record activity, resetting the stuck timer.
+      #
+      # @param message [String, nil] optional message describing the activity
+      # @return [void]
+      def record_activity(message = nil)
+        raise NotImplementedError, "#{self.class} must implement #record_activity"
+      end
+
+      # Mark the operation as completed successfully.
+      #
+      # @return [void]
+      def complete
+        raise NotImplementedError, "#{self.class} must implement #complete"
+      end
+
+      # Mark the operation as failed.
+      #
+      # @param error_message [String, nil] optional error description
+      # @return [void]
+      def fail(error_message = nil)
+        raise NotImplementedError, "#{self.class} must implement #fail"
+      end
+
+      # Check if the operation appears to be stuck.
+      #
+      # @return [Boolean] true if no activity for stuck_timeout seconds
+      def stuck?
+        raise NotImplementedError, "#{self.class} must implement #stuck?"
+      end
+
+      # Get the current activity state.
+      #
+      # @return [Symbol] one of STATES
+      def state
+        raise NotImplementedError, "#{self.class} must implement #state"
+      end
+
+      # Get elapsed time since start.
+      #
+      # @return [Float] seconds since monitoring started, or 0 if not started
+      def elapsed_time
+        raise NotImplementedError, "#{self.class} must implement #elapsed_time"
+      end
+
+      # Get a summary of the monitoring session.
+      #
+      # @return [Hash] summary with keys :step_name, :state, :elapsed_time, :stuck_detected, :output_count
+      def summary
+        raise NotImplementedError, "#{self.class} must implement #summary"
+      end
+    end
+
+    # NullActivityMonitor is a no-op implementation.
+    # Useful for testing or when monitoring is not needed.
+    #
+    class NullActivityMonitor
+      include ActivityMonitorInterface
+
+      def start(step_name:, stuck_timeout:, on_state_change: nil)
+        @state = :working
+      end
+
+      def record_activity(message = nil)
+        # no-op
+      end
+
+      def complete
+        @state = :completed
+      end
+
+      def fail(error_message = nil)
+        @state = :failed
+      end
+
+      def stuck?
+        false
+      end
+
+      def state
+        @state || :idle
+      end
+
+      def elapsed_time
+        0.0
+      end
+
+      def summary
+        {step_name: nil, state: state, elapsed_time: 0.0, stuck_detected: false, output_count: 0}
+      end
+    end
+
+    # ActivityMonitor is the standard implementation that tracks activity state.
+    #
+    # @example Basic usage
+    #   monitor = ActivityMonitor.new
+    #   monitor.start(step_name: "processing", stuck_timeout: 60)
+    #   monitor.record_activity("Started processing")
+    #   # ... do work ...
+    #   monitor.complete
+    #   puts monitor.summary
+    #
+    class ActivityMonitor
+      include ActivityMonitorInterface
+
+      attr_reader :state
+
+      DEFAULT_STUCK_TIMEOUT = 30
+
+      def initialize(logger: nil)
+        @logger = logger
+        @state = :idle
+        @start_time = nil
+        @last_activity_time = nil
+        @stuck_timeout = DEFAULT_STUCK_TIMEOUT
+        @step_name = nil
+        @on_state_change = nil
+        @output_count = 0
+      end
+
+      def start(step_name:, stuck_timeout: DEFAULT_STUCK_TIMEOUT, on_state_change: nil)
+        @step_name = step_name
+        @stuck_timeout = stuck_timeout
+        @on_state_change = on_state_change
+        @start_time = Time.now
+        @last_activity_time = @start_time
+        @output_count = 0
+        update_state(:working)
+        log_debug("started", step_name: step_name, stuck_timeout: stuck_timeout)
+      end
+
+      def record_activity(message = nil)
+        @output_count += 1
+        @last_activity_time = Time.now
+        update_state(:working, message)
+      end
+
+      def complete
+        update_state(:completed)
+        log_debug("completed", elapsed_time: elapsed_time, output_count: @output_count)
+      end
+
+      def fail(error_message = nil)
+        update_state(:failed, error_message)
+        log_debug("failed", error_message: error_message, elapsed_time: elapsed_time)
+      end
+
+      def stuck?
+        return false unless @state == :working
+        return false if @last_activity_time.nil?
+
+        seconds_since_activity = Time.now - @last_activity_time
+        if seconds_since_activity > @stuck_timeout
+          update_state(:stuck, "No activity for #{seconds_since_activity.round}s")
+          true
+        else
+          false
+        end
+      end
+
+      def elapsed_time
+        return 0.0 unless @start_time
+        Time.now - @start_time
+      end
+
+      def summary
+        {
+          step_name: @step_name,
+          state: @state,
+          start_time: @start_time&.iso8601,
+          elapsed_time: elapsed_time.round(2),
+          stuck_detected: @state == :stuck,
+          output_count: @output_count
+        }
+      end
+
+      private
+
+      def update_state(new_state, message = nil)
+        old_state = @state
+        @state = new_state
+        @on_state_change&.call(new_state, message) if old_state != new_state
+      end
+
+      def log_debug(message, **metadata)
+        @logger&.log_debug("activity_monitor", message, step_name: @step_name, **metadata)
+      end
+    end
+  end
+end