aidp 0.15.1 → 0.16.0

data/lib/aidp/init/runner.rb

@@ -12,20 +12,54 @@ module Aidp
     class Runner
       include Aidp::MessageDisplay
 
-      def initialize(project_dir = Dir.pwd, prompt: TTY::Prompt.new, analyzer: nil, doc_generator: nil)
+      def initialize(project_dir = Dir.pwd, prompt: TTY::Prompt.new, analyzer: nil, doc_generator: nil, options: {})
         @project_dir = project_dir
         @prompt = prompt
         @analyzer = analyzer || ProjectAnalyzer.new(project_dir)
         @doc_generator = doc_generator || DocGenerator.new(project_dir)
+        @options = options
       end
 
       def run
         display_message("🔍 Running aidp init project analysis...", type: :info)
-        analysis = @analyzer.analyze
-        display_summary(analysis)
+        analysis = @analyzer.analyze(explain_detection: @options[:explain_detection])
+
+        if @options[:explain_detection]
+          display_detailed_analysis(analysis)
+        else
+          display_summary(analysis)
+        end
+
+        # Dry run: skip preferences and generation
+        if @options[:dry_run]
+          display_message("\n🔍 Dry run mode - no files will be written.", type: :info)
+          return {
+            analysis: analysis,
+            preferences: {},
+            generated_files: []
+          }
+        end
 
         preferences = gather_preferences
 
+        # Offer preview before writing
+        if @options[:preview] || ask_yes_no_with_context(
+          "Preview generated files before saving?",
+          context: "Shows a summary of what will be written to docs/",
+          default: false
+        )
+          preview_generated_docs(analysis, preferences)
+
+          unless ask_yes_no("Proceed with writing these files?", default: true)
+            display_message("\n❌ Cancelled. No files were written.", type: :info)
+            return {
+              analysis: analysis,
+              preferences: preferences,
+              generated_files: []
+            }
+          end
+        end
+
         @doc_generator.generate(analysis: analysis, preferences: preferences)
 
         display_message("\n📄 Generated documentation:", type: :info)
@@ -52,24 +86,170 @@ module Aidp
         frameworks = analysis[:frameworks]
         tests = analysis[:test_frameworks]
         config_files = analysis[:config_files]
+        tooling = analysis[:tooling]
+
+        # Extract high-confidence frameworks (>= 0.7)
+        confident_frameworks = frameworks.select { |f| f[:confidence] >= 0.7 }.map { |f| f[:name] }
+        uncertain_frameworks = frameworks.select { |f| f[:confidence] < 0.7 }
+
+        # Extract high-confidence test frameworks (>= 0.7)
+        confident_tests = tests.select { |t| t[:confidence] >= 0.7 }.map { |t| t[:name] }
+
+        # Extract high-confidence tooling (>= 0.7)
+        confident_tooling = tooling.select { |t| t[:confidence] >= 0.7 }.map { |t| format_tool(t[:tool]) }
 
         display_message("\n📊 Repository Snapshot", type: :highlight)
         display_message("  Languages: #{languages.empty? ? "Unknown" : languages.join(", ")}", type: :info)
-        display_message("  Frameworks: #{frameworks.empty? ? "None detected" : frameworks.join(", ")}", type: :info)
-        display_message("  Test suites: #{tests.empty? ? "Not found" : tests.join(", ")}", type: :info)
-        display_message("  Config files: #{config_files.empty? ? "None detected" : config_files.join(", ")}", type: :info)
+
+        if confident_frameworks.any?
+          display_message("  Frameworks: #{confident_frameworks.join(", ")}", type: :info)
+        else
+          display_message("  Frameworks: None confidently detected", type: :info)
+        end
+
+        if uncertain_frameworks.any?
+          uncertain_list = uncertain_frameworks.map { |f| "#{f[:name]} (#{(f[:confidence] * 100).round}%)" }.join(", ")
+          display_message("  Possible frameworks: #{uncertain_list}", type: :info)
+        end
+
+        if confident_tests.any?
+          display_message("  Test suites: #{confident_tests.join(", ")}", type: :info)
+        else
+          display_message("  Test suites: Not found", type: :info)
+        end
+
+        if confident_tooling.any?
+          display_message("  Quality tools: #{confident_tooling.join(", ")}", type: :info)
+        end
+
+        display_message("  Config files: #{config_files.empty? ? "None detected" : config_files.size} found", type: :info)
+      end
+
+      def display_detailed_analysis(analysis)
+        display_message("\n🔍 Detailed Detection Analysis", type: :highlight)
+        display_message("=" * 60, type: :info)
+
+        # Languages
+        display_message("\n📝 Languages (by file size):", type: :highlight)
+        if analysis[:languages].any?
+          total_size = analysis[:languages].values.sum
+          analysis[:languages].each do |lang, size|
+            percentage = ((size.to_f / total_size) * 100).round(1)
+            display_message("  • #{lang}: #{percentage}%", type: :info)
+          end
+        else
+          display_message("  None detected", type: :info)
+        end
+
+        # Frameworks
+        display_message("\n🎯 Frameworks:", type: :highlight)
+        if analysis[:frameworks].any?
+          analysis[:frameworks].each do |fw|
+            confidence_pct = (fw[:confidence] * 100).round
+            display_message("  • #{fw[:name]} (#{confidence_pct}% confidence):", type: :info)
+            fw[:evidence].each do |evidence|
+              display_message("    - #{evidence}", type: :info)
+            end
+          end
+        else
+          display_message("  None detected", type: :info)
+        end
+
+        # Test Frameworks
+        display_message("\n🧪 Test Frameworks:", type: :highlight)
+        if analysis[:test_frameworks].any?
+          analysis[:test_frameworks].each do |test|
+            confidence_pct = (test[:confidence] * 100).round
+            display_message("  • #{test[:name]} (#{confidence_pct}% confidence):", type: :info)
+            test[:evidence].each do |evidence|
+              display_message("    - #{evidence}", type: :info)
+            end
+          end
+        else
+          display_message("  None detected", type: :info)
+        end
+
+        # Tooling
+        display_message("\n🔧 Quality Tooling:", type: :highlight)
+        if analysis[:tooling].any?
+          analysis[:tooling].each do |tool_data|
+            tool_name = format_tool(tool_data[:tool])
+            confidence_pct = (tool_data[:confidence] * 100).round
+            display_message("  • #{tool_name} (#{confidence_pct}% confidence):", type: :info)
+            tool_data[:evidence].each do |evidence|
+              display_message("    - #{evidence}", type: :info)
+            end
+          end
+        else
+          display_message("  None detected", type: :info)
+        end
+
+        # Key Directories
+        display_message("\n📁 Key Directories:", type: :highlight)
+        if analysis[:key_directories].any?
+          analysis[:key_directories].each do |dir|
+            display_message("  • #{dir}", type: :info)
+          end
+        else
+          display_message("  None detected", type: :info)
+        end
+
+        # Config Files
+        display_message("\n⚙️  Configuration Files:", type: :highlight)
+        if analysis[:config_files].any?
+          analysis[:config_files].each do |file|
+            display_message("  • #{file}", type: :info)
+          end
+        else
+          display_message("  None detected", type: :info)
+        end
+
+        # Repository Stats
+        display_message("\n📈 Repository Stats:", type: :highlight)
+        stats = analysis[:repo_stats]
+        display_message("  • Total files: #{stats[:total_files]}", type: :info)
+        display_message("  • Total directories: #{stats[:total_directories]}", type: :info)
+        display_message("  • Documentation: #{stats[:docs_present] ? "Present" : "Not found"}", type: :info)
+        display_message("  • CI/CD config: #{stats[:has_ci_config] ? "Present" : "Not found"}", type: :info)
+        display_message("  • Containerization: #{stats[:has_containerization] ? "Present" : "Not found"}", type: :info)
+
+        display_message("\n" + "=" * 60, type: :info)
+      end
+
+      def format_tool(tool)
+        tool.to_s.split("_").map(&:capitalize).join(" ")
       end
 
       def gather_preferences
-        display_message("\n⚙️  Customise bootstrap plans (press Enter to accept defaults):", type: :info)
+        display_message("\n⚙️  Configuration Options", type: :highlight)
+        display_message("The following questions will help customize the generated documentation.", type: :info)
+        display_message("Press Enter to accept defaults shown in brackets.\n", type: :info)
 
         {
-          adopt_new_conventions: ask_yes_no("Adopt the newly generated conventions as canonical defaults?", default: true),
-          stricter_linters: ask_yes_no("Enforce stricter linting based on detected tools?", default: false),
-          migrate_styles: ask_yes_no("Plan migrations to align legacy files with the new style guide?", default: false)
+          adopt_new_conventions: ask_yes_no_with_context(
+            "Make these conventions official for this repository?",
+            context: "This saves the detected patterns to LLM_STYLE_GUIDE.md and guides future AI-assisted work.",
+            default: true
+          ),
+          stricter_linters: ask_yes_no_with_context(
+            "Enable stricter linting rules in the quality plan?",
+            context: "Recommends failing CI on linting violations for better code quality.",
+            default: false
+          ),
+          migrate_styles: ask_yes_no_with_context(
+            "Plan gradual migration of legacy code to new style guide?",
+            context: "Adds migration tasks to CODE_QUALITY_PLAN.md for incremental improvements.",
+            default: false
+          )
         }
       end
 
+      def ask_yes_no_with_context(question, context:, default:)
+        display_message("\n#{question}", type: :info)
+        display_message("  ℹ️  #{context}", type: :info)
+        ask_yes_no(question, default: default)
+      end
+
       def ask_yes_no(question, default:)
         @prompt.yes?(question) do |q|
           q.default default ? "yes" : "no"
@@ -78,6 +258,79 @@ module Aidp
         # Compatibility with simplified prompts in tests (e.g. TestPrompt)
         default
       end
+
+      def preview_generated_docs(analysis, preferences)
+        display_message("\n📄 Preview of Generated Documentation", type: :highlight)
+        display_message("=" * 60, type: :info)
+
+        # LLM_STYLE_GUIDE summary
+        display_message("\n1. docs/LLM_STYLE_GUIDE.md", type: :highlight)
+        confident_frameworks = analysis[:frameworks].select { |f| f[:confidence] >= 0.7 }.map { |f| f[:name] }
+        display_message("   - Detected frameworks: #{confident_frameworks.any? ? confident_frameworks.join(", ") : "None"}", type: :info)
+        display_message("   - Adoption status: #{preferences[:adopt_new_conventions] ? "Official conventions" : "Optional reference"}", type: :info)
+
+        # PROJECT_ANALYSIS summary
+        display_message("\n2. docs/PROJECT_ANALYSIS.md", type: :highlight)
+        display_message("   - Languages: #{analysis[:languages].keys.join(", ")}", type: :info)
+        display_message("   - Total frameworks detected: #{analysis[:frameworks].size}", type: :info)
+        display_message("   - Test frameworks: #{analysis[:test_frameworks].map { |t| t[:name] }.join(", ") || "None"}", type: :info)
+
+        # CODE_QUALITY_PLAN summary
+        display_message("\n3. docs/CODE_QUALITY_PLAN.md", type: :highlight)
+        tooling_count = analysis[:tooling].count { |t| t[:confidence] >= 0.7 }
+        display_message("   - Quality tools detected: #{tooling_count}", type: :info)
+        display_message("   - Stricter linting: #{preferences[:stricter_linters] ? "Yes" : "No"}", type: :info)
+        display_message("   - Migration planning: #{preferences[:migrate_styles] ? "Yes" : "No"}", type: :info)
+
+        # Validation warnings
+        validate_tooling(analysis)
+
+        display_message("\n" + "=" * 60, type: :info)
+      end
+
+      def validate_tooling(analysis)
+        display_message("\n🔍 Validation", type: :highlight)
+
+        warnings = []
+
+        # Check if detected tools actually exist
+        analysis[:tooling].select { |t| t[:confidence] >= 0.7 }.each do |tool_data|
+          tool_name = tool_data[:tool].to_s
+
+          # Try to find the tool command
+          tool_command = case tool_name
+          when "rubocop", "standardrb", "eslint", "prettier", "stylelint", "flake8", "black", "pytest", "jest"
+            tool_name
+          when "cargo_fmt"
+            "cargo"
+          when "gofmt"
+            "gofmt"
+          end
+
+          next unless tool_command
+
+          # Check if command exists
+          unless system("which #{tool_command} > /dev/null 2>&1")
+            warnings << "   ⚠️  #{format_tool(tool_data[:tool])} detected but command '#{tool_command}' not found in PATH"
+          end
+        end
+
+        # Check if test commands can be inferred
+        if analysis[:test_frameworks].empty?
+          warnings << "   ⚠️  No test framework detected - consider adding one for better quality assurance"
+        end
+
+        # Check for CI configuration
+        unless analysis[:repo_stats][:has_ci_config]
+          warnings << "   ℹ️  No CI configuration detected - consider adding GitHub Actions or similar"
+        end
+
+        if warnings.any?
+          warnings.each { |warning| display_message(warning, type: :info) }
+        else
+          display_message("   ✅ All detected tools validated successfully", type: :success)
+        end
+      end
     end
   end
 end

data/lib/aidp/jobs/background_runner.rb

@@ -3,7 +3,9 @@
 require "securerandom"
 require "yaml"
 require "fileutils"
+require "time"
 require_relative "../rescue_logging"
+require_relative "../concurrency"
 
 module Aidp
   module Jobs
@@ -69,7 +71,14 @@ module Aidp
 
         # Wait for child to fork
         Process.detach(pid)
-        sleep 0.1 # Give daemon time to write PID file
+
+        # Wait for daemon to write PID file (with timeout)
+        begin
+          Aidp::Concurrency::Wait.for_file(pid_file, timeout: 5, interval: 0.05)
+        rescue Aidp::Concurrency::TimeoutError
+          # PID file not created - daemon may have failed to start
+          # Continue anyway, metadata will reflect this
+        end
 
         # Save job metadata in parent process
         save_job_metadata(job_id, pid, mode, options)
@@ -191,7 +200,7 @@ module Aidp
           job_id: job_id,
           pid: pid,
           mode: mode,
-          started_at: Time.now,
+          started_at: Time.now.iso8601,
           status: "running",
           options: options.except(:prompt) # Don't save prompt object
         }
@@ -203,6 +212,7 @@ module Aidp
         metadata_file = File.join(@jobs_dir, job_id, "metadata.yml")
         return nil unless File.exist?(metadata_file)
 
+        # Return raw metadata with times as ISO8601 strings to avoid unsafe class loading
         YAML.load_file(metadata_file)
       rescue
         nil
@@ -220,7 +230,7 @@ module Aidp
       def mark_job_completed(job_id, result)
         update_job_metadata(job_id, {
           status: "completed",
-          completed_at: Time.now,
+          completed_at: Time.now.iso8601,
           result: result
         })
       end
@@ -228,7 +238,7 @@ module Aidp
       def mark_job_failed(job_id, error)
         update_job_metadata(job_id, {
           status: "failed",
-          completed_at: Time.now,
+          completed_at: Time.now.iso8601,
           error: {
             message: error.message,
             class: error.class.name,
@@ -240,7 +250,7 @@ module Aidp
       def mark_job_stopped(job_id)
         update_job_metadata(job_id, {
           status: "stopped",
-          completed_at: Time.now
+          completed_at: Time.now.iso8601
         })
       end
 

data/lib/aidp/logger.rb

@@ -104,10 +104,21 @@ module Aidp
     end
 
     def create_logger(path)
+      # Ensure parent directory exists before creating logger
+      dir = File.dirname(path)
+      FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+
       logger = ::Logger.new(path, @max_files, @max_size)
       logger.level = ::Logger::DEBUG # Control at write level instead
       logger.formatter = proc { |severity, datetime, progname, msg| "#{msg}\n" }
       logger
+    rescue => e
+      # Fall back to STDERR if file logging fails
+      warn "[AIDP Logger] Failed to create log file at #{path}: #{e.message}. Falling back to STDERR."
+      logger = ::Logger.new($stderr)
+      logger.level = ::Logger::DEBUG
+      logger.formatter = proc { |severity, datetime, progname, msg| "#{msg}\n" }
+      logger
     end
 
     def write_entry(level, component, message, metadata)

data/lib/aidp/providers/codex.rb

@@ -57,7 +57,6 @@ module Aidp
         spinner = TTY::Spinner.new("[:spinner] :title", format: :dots, hide_cursor: true)
         spinner.auto_spin
 
-        # Start activity display thread with timeout
         activity_display_thread = Thread.new do
           start_time = Time.now
           loop do

data/lib/aidp/providers/cursor.rb

@@ -54,7 +54,6 @@ module Aidp
         spinner = TTY::Spinner.new("[:spinner] :title", format: :dots, hide_cursor: true)
         spinner.auto_spin
 
-        # Start activity display thread with timeout
         activity_display_thread = Thread.new do
           start_time = Time.now
           loop do

data/lib/aidp/providers/github_copilot.rb

@@ -57,7 +57,6 @@ module Aidp
         spinner = TTY::Spinner.new("[:spinner] :title", format: :dots, hide_cursor: true)
         spinner.auto_spin
 
-        # Start activity display thread with timeout
         activity_display_thread = Thread.new do
           start_time = Time.now
           loop do

data/lib/aidp/providers/opencode.rb

@@ -50,7 +50,6 @@ module Aidp
         spinner = TTY::Spinner.new("[:spinner] :title", format: :dots, hide_cursor: true)
         spinner.auto_spin
 
-        # Start activity display thread with timeout
         activity_display_thread = Thread.new do
           start_time = Time.now
           loop do

data/lib/aidp/skills/composer.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Aidp
+  module Skills
+    # Composes skills with templates to create complete prompts
+    #
+    # The Composer combines skill content (WHO the agent is and WHAT capabilities
+    # they have) with template content (WHEN/HOW to execute a specific task).
+    #
+    # Composition structure:
+    #   1. Skill content (persona, expertise, philosophy)
+    #   2. Separator
+    #   3. Template content (task-specific instructions)
+    #
+    # @example Basic composition
+    #   composer = Composer.new
+    #   prompt = composer.compose(
+    #     skill: repository_analyst_skill,
+    #     template: "Analyze the repository..."
+    #   )
+    #
+    # @example Template-only (no skill)
+    #   prompt = composer.compose(template: "Do this task...")
+    class Composer
+      # Separator between skill and template content
+      SKILL_TEMPLATE_SEPARATOR = "\n\n---\n\n"
+
+      # Compose a skill and template into a complete prompt
+      #
+      # @param skill [Skill, nil] Skill to include (optional)
+      # @param template [String] Template content
+      # @param options [Hash] Optional parameters for template variable replacement
+      # @return [String] Composed prompt
+      def compose(template:, skill: nil, options: {})
+        Aidp.log_debug(
+          "skills",
+          "Composing prompt",
+          skill_id: skill&.id,
+          template_length: template.length,
+          options_count: options.size
+        )
+
+        # Replace template variables
+        rendered_template = render_template(template, options: options)
+
+        # If no skill, return template only
+        unless skill
+          Aidp.log_debug("skills", "Template-only composition", template_length: rendered_template.length)
+          return rendered_template
+        end
+
+        # Compose skill + template
+        composed = [
+          skill.content,
+          SKILL_TEMPLATE_SEPARATOR,
+          "# Current Task",
+          "",
+          rendered_template
+        ].join("\n")
+
+        Aidp.log_debug(
+          "skills",
+          "Composed prompt with skill",
+          skill_id: skill.id,
+          total_length: composed.length,
+          skill_length: skill.content.length,
+          template_length: rendered_template.length
+        )
+
+        composed
+      end
+
+      # Render a template with variable substitution
+      #
+      # Replaces {{variable}} placeholders with values from options hash
+      #
+      # @param template [String] Template content
+      # @param options [Hash] Variable values for substitution
+      # @return [String] Rendered template
+      def render_template(template, options: {})
+        return template if options.empty?
+
+        rendered = template.dup
+
+        options.each do |key, value|
+          placeholder = "{{#{key}}}"
+          rendered = rendered.gsub(placeholder, value.to_s)
+        end
+
+        # Log if there are unreplaced placeholders
+        remaining_placeholders = extract_placeholders(rendered)
+        if remaining_placeholders.any?
+          Aidp.log_warn(
+            "skills",
+            "Unreplaced template variables",
+            placeholders: remaining_placeholders
+          )
+        end
+
+        rendered
+      end
+
+      # Compose multiple skills with a template
+      #
+      # Note: This is for future use when skill composition is supported.
+      # Currently raises an error as it's not implemented in v1.
+      #
+      # @param skills [Array<Skill>] Skills to compose
+      # @param template [String] Template content
+      # @param options [Hash] Template variables
+      # @return [String] Composed prompt
+      # @raise [NotImplementedError] Skill composition not yet supported
+      def compose_multiple(skills:, template:, options: {})
+        raise NotImplementedError, "Multiple skill composition not yet supported in v1"
+      end
+
+      # Preview what a composed prompt would look like
+      #
+      # Returns a hash with skill content, template content, and full composition
+      # for inspection without executing.
+      #
+      # @param skill [Skill, nil] Skill to include
+      # @param template [String] Template content
+      # @param options [Hash] Template variables
+      # @return [Hash] Preview with :skill, :template, :composed, :metadata
+      def preview(template:, skill: nil, options: {})
+        rendered_template = render_template(template, options: options)
+        composed = compose(skill: skill, template: template, options: options)
+
+        {
+          skill: skill ? {
+            id: skill.id,
+            name: skill.name,
+            content: skill.content,
+            length: skill.content.length
+          } : nil,
+          template: {
+            content: rendered_template,
+            length: rendered_template.length,
+            variables: options.keys
+          },
+          composed: {
+            content: composed,
+            length: composed.length
+          },
+          metadata: {
+            has_skill: !skill.nil?,
+            separator_used: !skill.nil?,
+            unreplaced_vars: extract_placeholders(composed)
+          }
+        }
+      end
+
+      private
+
+      def extract_placeholders(text)
+        return [] if text.nil? || text.empty?
+
+        scanner = StringScanner.new(text)
+        placeholders = []
+
+        while scanner.skip_until(/\{\{/)
+          fragment = scanner.scan_until(/\}\}/)
+          break unless fragment
+
+          placeholder = fragment[0...-2]
+          next if placeholder.nil? || placeholder.empty? || placeholder.include?("{")
+
+          placeholders << placeholder
+        end
+
+        placeholders
+      end
+    end
+  end
+end