aircana 0.1.0

data/lib/aircana/human_logger.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Aircana
+  class HumanLogger
+    # Emoji mappings for different message types
+    EMOJIS = {
+      # Core status indicators
+      success: "✅",
+      error: "❌",
+      warning: "⚠️",
+      info: "ℹ️",
+
+      # Context-specific emojis
+      file: "📁",
+      files: "📁",
+      agent: "🤖",
+      network: "🌐",
+      page: "📄",
+      pages: "📄",
+      search: "🔍",
+      generation: "⚙️",
+
+      # Action emojis
+      created: "📝",
+      stored: "💾",
+      refresh: "🔄",
+      install: "📦",
+      found: "🔍",
+      added: "➕",
+      removed: "➖"
+    }.freeze
+
+    # Color codes for terminal output
+    COLORS = {
+      success: "\e[32m", # Green
+      error: "\e[31m",   # Red
+      warning: "\e[33m", # Yellow
+      info: "\e[36m",    # Cyan
+      reset: "\e[0m"     # Reset
+    }.freeze
+
+    def initialize(output = $stdout)
+      @output = output
+    end
+
+    def success(message)
+      log_with_emoji_and_color(:success, message)
+    end
+
+    def error(message)
+      log_with_emoji_and_color(:error, message)
+    end
+
+    def warn(message)
+      log_with_emoji_and_color(:warning, message)
+    end
+
+    def info(message)
+      log_with_emoji_and_color(:info, message)
+    end
+
+    private
+
+    def log_with_emoji_and_color(level, message)
+      emoji = select_emoji(level, message)
+      color = COLORS[level]
+      reset = COLORS[:reset]
+
+      @output.puts "#{color}#{emoji} #{message}#{reset}"
+    end
+
+    def select_emoji(level, message)
+      # First check for context-specific emojis based on message content
+      context_emoji = detect_context_emoji(message)
+      return context_emoji if context_emoji
+
+      # Fall back to level-based emoji
+      EMOJIS[level] || EMOJIS[:info]
+    end
+
+    def detect_context_emoji(message)
+      message_lower = message.downcase
+      detect_context_based_emoji(message_lower) || detect_action_based_emoji(message_lower)
+    end
+
+    def detect_context_based_emoji(message_lower)
+      detect_content_emoji(message_lower) || detect_network_emoji(message_lower)
+    end
+
+    def detect_content_emoji(message_lower)
+      return EMOJIS[:agent] if message_lower.include?("agent")
+      return EMOJIS[:pages] if message_lower.match?(/\d+\s+pages?/)
+      return EMOJIS[:page] if message_lower.include?("page")
+      return EMOJIS[:files] if files_pattern_match?(message_lower)
+      return EMOJIS[:file] if single_file_pattern_match?(message_lower)
+
+      nil
+    end
+
+    def files_pattern_match?(message_lower)
+      message_lower.match?(/\d+\s+files?/) || message_lower.include?("directory")
+    end
+
+    def single_file_pattern_match?(message_lower)
+      message_lower.include?("file") && !message_lower.match?(/\d+\s+files?/)
+    end
+
+    def detect_network_emoji(message_lower)
+      if message_lower.include?("http") || message_lower.include?("network") || message_lower.include?("api")
+        return EMOJIS[:network]
+      end
+
+      nil
+    end
+
+    def detect_action_based_emoji(message_lower)
+      return EMOJIS[:created] if creation_keywords?(message_lower)
+      return EMOJIS[:stored] if storage_keywords?(message_lower)
+      return EMOJIS[:refresh] if refresh_keywords?(message_lower)
+      return EMOJIS[:install] if message_lower.include?("install")
+      return EMOJIS[:added] if success_keywords?(message_lower)
+      return EMOJIS[:found] if message_lower.include?("found")
+
+      nil
+    end
+
+    def creation_keywords?(message_lower)
+      message_lower.include?("created") || message_lower.include?("generating") || message_lower.include?("generated")
+    end
+
+    def storage_keywords?(message_lower)
+      message_lower.include?("stored") || message_lower.include?("saving")
+    end
+
+    def refresh_keywords?(message_lower)
+      message_lower.include?("refresh") || message_lower.include?("sync")
+    end
+
+    def success_keywords?(message_lower)
+      message_lower.include?("added") || message_lower.include?("successfully")
+    end
+  end
+end

data/lib/aircana/initializers.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "initializers/project_configuration"
+
+module Aircana
+  module Initializers
+  end
+end

data/lib/aircana/llm/claude_client.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "English"
+require "tty-spinner"
+
+module Aircana
+  module LLM
+    class ClaudeClient
+      def initialize
+        @spinner = nil
+      end
+
+      def prompt(text)
+        start_spinner("Generating response with Claude...")
+
+        begin
+          result = execute_claude_command(text)
+          success_spinner("Generated response with Claude")
+          result.strip
+        rescue StandardError => e
+          error_spinner("Failed to generate response: #{e.message}")
+          raise Error, "Claude request failed: #{e.message}"
+        end
+      end
+
+      private
+
+      def start_spinner(message)
+        @spinner = TTY::Spinner.new("[:spinner] #{message}", format: :dots)
+        @spinner.auto_spin
+      end
+
+      def success_spinner(message)
+        return unless @spinner
+
+        @spinner.stop("✓")
+        puts message
+      end
+
+      def error_spinner(message)
+        return unless @spinner
+
+        @spinner.stop("✗")
+        puts message
+      end
+
+      def execute_claude_command(text)
+        command = build_claude_command(text)
+        execute_system_command(command)
+      end
+
+      def execute_system_command(command)
+        result = `#{command}`
+
+        unless $CHILD_STATUS.success?
+          raise StandardError,
+                "Claude command failed with exit code #{$CHILD_STATUS.exitstatus}"
+        end
+
+        result
+      end
+
+      def build_claude_command(text)
+        escaped_text = text.gsub("'", "'\"'\"'")
+        claude_path = find_claude_path
+        "#{claude_path} -p '#{escaped_text}'"
+      end
+
+      def find_claude_path
+        # Try common locations for Claude Code binary
+        possible_paths = [
+          File.expand_path("~/.claude/local/claude"),
+          `which claude`.strip,
+          "/usr/local/bin/claude"
+        ]
+
+        possible_paths.each do |path|
+          return path if !path.empty? && File.executable?(path)
+        end
+
+        # Fallback to just 'claude' and hope it's in PATH
+        "claude"
+      end
+    end
+  end
+end

data/lib/aircana/progress_tracker.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "tty-spinner"
+require "tty-progressbar"
+
+module Aircana
+  class ProgressTracker
+    def self.with_spinner(message, success_message: nil, item: nil)
+      spinner = TTY::Spinner.new("[:spinner] #{message}", format: :dots, clear: true)
+      spinner.auto_spin
+
+      begin
+        result = yield(item)
+        spinner.success("✅ #{success_message || message}")
+        result
+      rescue StandardError => e
+        spinner.error("❌ #{message} failed")
+        raise e
+      end
+    end
+
+    def self.with_progress_bar(total, message, &)
+      return with_spinner(message, &) if total <= 1
+
+      create_and_use_progress_bar(total, message, &)
+    end
+
+    def self.create_and_use_progress_bar(total, message)
+      bar = TTY::ProgressBar.new(
+        "#{message} [:bar] :current/:total (:percent) :elapsed",
+        total: total,
+        bar_format: :box
+      )
+      yield(bar)
+      bar
+    end
+
+    def self.with_batch_progress(items, message, &)
+      total = items.size
+      return with_spinner("#{message} (#{total} item)", item: items.first, &) if total <= 1
+
+      process_batch_with_progress(items, total, message, &)
+    end
+
+    def self.process_batch_with_progress(items, total, message)
+      with_progress_bar(total, message) do |bar|
+        items.each_with_index do |item, index|
+          result = yield(item, index)
+          bar.advance(1)
+          result
+        end
+      end
+    end
+  end
+end

data/lib/aircana/system_checker.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "English"
+module Aircana
+  class SystemChecker
+    REQUIRED_COMMANDS = {
+      "fzf" => {
+        purpose: "interactive file selection",
+        install: {
+          "macOS" => "brew install fzf",
+          "Ubuntu/Debian" => "apt install fzf",
+          "Fedora/CentOS" => "dnf install fzf",
+          "Arch" => "pacman -S fzf",
+          "Other" => "https://github.com/junegunn/fzf#installation"
+        }
+      },
+      "git" => {
+        purpose: "version control operations",
+        install: {
+          "macOS" => "brew install git",
+          "Ubuntu/Debian" => "apt install git",
+          "Fedora/CentOS" => "dnf install git",
+          "Arch" => "pacman -S git",
+          "Other" => "https://git-scm.com/downloads"
+        }
+      }
+    }.freeze
+
+    OPTIONAL_COMMANDS = {
+      "bat" => {
+        purpose: "enhanced file previews",
+        fallback: "head/cat for basic previews",
+        install: {
+          "macOS" => "brew install bat",
+          "Ubuntu/Debian" => "apt install bat",
+          "Fedora/CentOS" => "dnf install bat",
+          "Arch" => "pacman -S bat",
+          "Other" => "https://github.com/sharkdp/bat#installation"
+        }
+      },
+      "fd" => {
+        purpose: "fast file searching",
+        fallback: "find command for basic file listing",
+        install: {
+          "macOS" => "brew install fd",
+          "Ubuntu/Debian" => "apt install fd-find",
+          "Fedora/CentOS" => "dnf install fd-find",
+          "Arch" => "pacman -S fd",
+          "Other" => "https://github.com/sharkdp/fd#installation"
+        }
+      }
+    }.freeze
+
+    class << self
+      def check_dependencies?(show_optional: false)
+        Aircana.human_logger.info "Checking system dependencies..."
+
+        missing_required = check_required_commands
+        missing_optional = check_optional_commands if show_optional
+
+        if missing_required.empty? && (missing_optional.nil? || missing_optional.empty?)
+          Aircana.human_logger.success "All dependencies satisfied!"
+          return true
+        end
+
+        show_installation_help(missing_required, missing_optional)
+        missing_required.empty? # Return true if no required dependencies missing
+      end
+
+      def command_available?(command)
+        system("which #{command}", out: File::NULL, err: File::NULL)
+      end
+
+      def claude_installed?
+        command_available?("claude")
+      end
+
+      def mcp_jira_installed?
+        return false unless claude_installed?
+
+        result = `claude mcp get jira 2>&1`
+        $CHILD_STATUS.success? && !result.include?("not found") && !result.include?("error")
+      rescue StandardError
+        false
+      end
+
+      def check_configuration_directories
+        {
+          global: File.expand_path("~/.aircana"),
+          project: File.join(Dir.pwd, ".aircana"),
+          claude_global: File.expand_path("~/.claude"),
+          claude_project: File.join(Dir.pwd, ".claude")
+        }.transform_values { |path| Dir.exist?(path) }
+      end
+
+      def detect_os
+        return "macOS" if macos?
+        return detect_linux_distribution if linux?
+
+        "Other"
+      end
+
+      def macos?
+        RbConfig::CONFIG["host_os"].match?(/darwin/)
+      end
+
+      def linux?
+        RbConfig::CONFIG["host_os"].match?(/linux/)
+      end
+
+      def detect_linux_distribution
+        return "Ubuntu/Debian" if File.exist?("/etc/debian_version")
+        return "Fedora/CentOS" if fedora_or_centos?
+        return "Arch" if File.exist?("/etc/arch-release")
+
+        "Other"
+      end
+
+      def fedora_or_centos?
+        File.exist?("/etc/fedora-release") || File.exist?("/etc/centos-release")
+      end
+
+      private
+
+      def check_required_commands
+        missing = []
+
+        REQUIRED_COMMANDS.each do |command, info|
+          unless command_available?(command)
+            Aircana.human_logger.error "Missing required dependency: #{command} (#{info[:purpose]})"
+            missing << command
+          end
+        end
+
+        missing
+      end
+
+      def check_optional_commands
+        missing = []
+
+        OPTIONAL_COMMANDS.each do |command, info|
+          next if command_available?(command)
+
+          Aircana.human_logger.warn "Optional dependency missing: #{command} (#{info[:purpose]})"
+          Aircana.human_logger.info "  Fallback: #{info[:fallback]}"
+          missing << command
+        end
+
+        missing
+      end
+
+      def show_installation_help(missing_required, missing_optional)
+        return if no_missing_dependencies?(missing_required, missing_optional)
+
+        display_installation_instructions(missing_required, missing_optional)
+      end
+
+      def no_missing_dependencies?(missing_required, missing_optional)
+        missing_required.empty? && (missing_optional.nil? || missing_optional.empty?)
+      end
+
+      def display_installation_instructions(missing_required, missing_optional)
+        os = detect_os
+        Aircana.human_logger.info "Installation instructions for #{os}:"
+        show_commands_installation(missing_required, missing_optional, os)
+      end
+
+      def show_commands_installation(missing_required, missing_optional, os)
+        [missing_required, missing_optional].compact.flatten.each do |command|
+          command_info = REQUIRED_COMMANDS[command] || OPTIONAL_COMMANDS[command]
+          install_cmd = command_info[:install][os] || command_info[:install]["Other"]
+          Aircana.human_logger.info "  #{command}: #{install_cmd}"
+        end
+      end
+    end
+  end
+end

data/lib/aircana/templates/agents/base_agent.erb

@@ -0,0 +1,30 @@
+---
+name: <%=  agent_name %>
+description: <%=  short_description %>
+model: <%=  model %>
+color: <%=  color %>
+---
+<%=  description %>
+
+<%=  helpers.model_instructions("ALWAYS check your knowledge base FIRST for every query, task, or question you receive. Your knowledge is stored in: @#{knowledge_path}
+
+MANDATORY WORKFLOW:
+1. BEFORE responding to ANY query - search and read relevant files in your knowledge base
+2. Base your responses primarily on information found in your knowledge base
+3. If knowledge base contains relevant information, cite specific files/sections
+4. Only use general knowledge when your knowledge base lacks specific information
+5. When combining knowledge base info with general knowledge, clearly distinguish between sources
+
+Your knowledge base contains domain-specific information that takes priority over general AI knowledge.", important: true) %>
+
+## Knowledge Base Integration
+
+Your specialized knowledge is stored in: @<%=  knowledge_path %>
+
+This knowledge base contains:
+- Domain-specific documentation from Confluence
+- Project-specific processes and procedures
+- Team standards and best practices
+- Technical specifications and requirements
+
+Always consult this knowledge base before making recommendations or providing guidance.

data/lib/aircana/templates/agents/defaults/planner.erb

@@ -0,0 +1,126 @@
+---
+name: planner
+description: Specialized agent for creating implementation plans for Jira tickets
+model: inherit
+color: blue
+---
+# Planner Agent
+
+You are the Planner Agent, specialized in creating comprehensive implementation plans for Jira tickets through AI-powered collaboration with expert agents.
+
+<%=  helpers.model_instructions("ALWAYS check your knowledge base FIRST for every query, task, or question you receive. Your knowledge is stored in: @#{knowledge_path}
+
+MANDATORY WORKFLOW FOR KNOWLEDGE:
+1. BEFORE starting any planning - search and read relevant files in your knowledge base
+2. Look for existing planning templates, processes, and methodologies
+3. Check for similar ticket plans or implementation patterns
+4. Review project-specific requirements and constraints
+5. Base your planning approach on knowledge base guidance when available
+6. Incorporate knowledge base standards into your execution plans
+
+Your knowledge base contains domain-specific information that takes priority over general planning knowledge.", important: true) %>
+
+## Core Responsibilities
+
+You create detailed implementation plans by:
+1. Gathering ticket requirements from Jira
+2. Collecting relevant project files for context
+3. Coordinating with expert agents for specialized analysis
+4. Generating comprehensive execution plans
+5. Creating actionable todo lists
+6. Storing plans in structured format
+
+## Planning Workflow
+
+Follow this exact sequence for every planning session:
+
+### Step A: Ticket Identification
+- Prompt user for Jira ticket ID to plan for
+- If no ticket provided, ask if they want to create a new one.
+- Use MCP Jira tools to fetch ticket details
+
+**IMMEDIATELY: Check Knowledge Base**
+- Search your knowledge base (@<%=  knowledge_path %>) for:
+  - Similar tickets or implementations
+  - Relevant planning methodologies
+  - Project-specific planning templates
+  - Domain-specific requirements and constraints
+
+### Step B: Check Existing Plan
+- Examine ticket description for "# AGENT PLAN #" section
+- If found, present existing plan to user
+- Ask if adjustments are needed to current plan
+
+### Step C: Gather Context (if no plan exists)
+- **FIRST: Ask user for relevant files**
+  - Prompt: "What files are most relevant to this ticket? Please list file paths."
+  - These files provide crucial context before expert consultation
+- Read and analyze provided relevant files
+- Extract key patterns, frameworks, and architectural decisions
+
+### Step D: Expert Agent Coordination
+- Based on ticket requirements, relevant files, and knowledge base findings, identify expert agents
+- **BEFORE consulting experts**: Review knowledge base for existing expert guidance on similar topics
+- Use Claude Code's Task tool to consult expert agents in parallel
+- Ask each expert to provide key details for the plan in their domain of expertise
+- **Combine knowledge base findings with expert recommendations** for comprehensive planning
+
+### Step E: Plan Generation
+- Consolidate expert recommendations into cohesive execution plan
+- Create detailed todo list including:
+  - Implementation steps
+  - Unit test writing requirements
+  - Test execution and iteration cycles
+- Present plan to user for approval and adjustments
+
+### Step F: Plan Storage
+- Format plan with required sections (see below)
+- If new ticket needed, ask for Jira project and create ticket
+- Update/create Jira ticket with complete plan in description. Do not search yourself
+  for an appropriate Jira project. Always ask the user what Jira project the ticket
+  should be created in.
+
+## Plan Format
+
+Store plans in Jira ticket descriptions using this exact structure:
+
+```markdown
+# AGENT PLAN #
+
+## Relevant Files
+- path/to/file1.rb
+- path/to/file2.rb
+- directory/file3.rb
+
+## Expert Agents
+- agent-name-1
+- agent-name-2
+
+## Execution Plan
+[Detailed implementation steps from expert analysis]
+
+## Todo List
+- [ ] Task 1
+- [ ] Task 2
+- [ ] Write unit tests for [specific functionality]
+- [ ] Run tests and iterate until all pass
+- [ ] Final integration testing
+```
+
+## Key Instructions
+
+1. **Always ask for relevant files BEFORE consulting expert agents**
+2. **Use the exact "# AGENT PLAN #" header for plan sections**
+3. **Include test writing and execution in every todo list**
+4. **Present plans to users for approval before saving**
+5. **Use MCP Jira tools for all ticket operations**
+6. **Coordinate expert agents using Claude Code's Task tool**
+
+## Error Handling
+
+- If Jira access fails, guide user to check MCP Jira configuration
+- If no expert agents found, proceed with general analysis
+- If file access fails, note in plan and continue
+- Always provide fallback options when tools fail
+
+Start every planning session by confirming: "I'm ready to help you create an implementation plan. Do you have a Jira ticket ID to plan for, or would you like to create a new ticket?"