aircana 0.1.0 → 1.1.0.rc1

data/lib/aircana/cli/commands/install.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+require "json"
 require_relative "generate"
+require_relative "../../generators/project_config_generator"
 
 module Aircana
   module CLI
@@ -8,7 +10,9 @@ module Aircana
       class << self
         def run
           ensure_output_exists
+          ensure_project_config_exists
           install_commands_to_claude
+          install_hooks_to_claude
         end
 
         private
@@ -20,6 +24,14 @@ module Aircana
           Generate.run
         end
 
+        def ensure_project_config_exists
+          project_json_path = File.join(Aircana.configuration.project_dir, ".aircana", "project.json")
+          return if File.exist?(project_json_path)
+
+          Aircana.human_logger.info("Creating project.json for multi-root support...")
+          Aircana::Generators::ProjectConfigGenerator.new.generate
+        end
+
         def install_commands_to_claude
           claude_commands_dir = File.join(Aircana.configuration.claude_code_project_config_path, "commands")
           Aircana.create_dir_if_needed(claude_commands_dir)
@@ -61,6 +73,107 @@ module Aircana
           require_relative "../../generators/agents_generator"
           Aircana::Generators::AgentsGenerator.available_default_agents.include?(agent_name)
         end
+
+        def install_hooks_to_claude
+          return unless Dir.exist?(Aircana.configuration.hooks_dir)
+
+          settings_file = File.join(Aircana.configuration.claude_code_project_config_path, "settings.local.json")
+          install_hooks_to_settings(settings_file)
+        end
+
+        def install_hooks_to_settings(settings_file)
+          settings = load_settings(settings_file)
+          hook_configs = build_hook_configs
+
+          return if hook_configs.empty?
+
+          settings["hooks"] = hook_configs
+          save_settings(settings_file, settings)
+
+          Aircana.human_logger.success("Installed hooks to #{settings_file}")
+        end
+
+        def load_settings(settings_file)
+          if File.exist?(settings_file)
+            JSON.parse(File.read(settings_file))
+          else
+            Aircana.create_dir_if_needed(File.dirname(settings_file))
+            {}
+          end
+        rescue JSON::ParserError
+          Aircana.human_logger.warn("Invalid JSON in #{settings_file}, creating new settings")
+          {}
+        end
+
+        def save_settings(settings_file, settings)
+          File.write(settings_file, JSON.pretty_generate(settings))
+        end
+
+        def build_hook_configs
+          hooks = {}
+
+          # Map hook files to Claude Code hook events and their properties
+          hook_mappings = {
+            "pre_tool_use" => { event: "PreToolUse", matcher: nil },
+            "post_tool_use" => { event: "PostToolUse", matcher: nil },
+            "user_prompt_submit" => { event: "UserPromptSubmit", matcher: nil },
+            "session_start" => { event: "SessionStart", matcher: nil },
+            "rubocop_pre_commit" => { event: "PreToolUse", matcher: "Bash" },
+            "rspec_test" => { event: "PostToolUse", matcher: "Bash" },
+            "bundle_install" => { event: "PostToolUse", matcher: "Bash" }
+          }
+
+          Dir.glob("#{Aircana.configuration.hooks_dir}/*.sh").each do |hook_file|
+            hook_name = File.basename(hook_file, ".sh")
+
+            # Determine mapping for this hook
+            mapping = if hook_mappings.key?(hook_name)
+                        hook_mappings[hook_name]
+                      else
+                        # For custom hooks, try to infer the event type from the filename
+                        infer_hook_mapping(hook_name)
+                      end
+
+            next unless mapping
+
+            event_key = mapping[:event]
+
+            # Create relative path from project root
+            relative_path = File.join(".aircana", "hooks", "#{hook_name}.sh")
+
+            hook_entry = {
+              "hooks" => [
+                {
+                  "type" => "command",
+                  "command" => relative_path
+                }
+              ]
+            }
+
+            # Add matcher if specified
+            hook_entry["matcher"] = mapping[:matcher] if mapping[:matcher]
+
+            hooks[event_key] ||= []
+            hooks[event_key] << hook_entry
+          end
+
+          hooks
+        end
+
+        def infer_hook_mapping(hook_name)
+          # Try to infer the event type from common patterns in the hook name
+          case hook_name
+          when /pre_tool_use|pre_tool|before_tool/i
+            { event: "PreToolUse", matcher: nil }
+          when /user_prompt|prompt_submit|before_prompt/i
+            { event: "UserPromptSubmit", matcher: nil }
+          when /session_start|session_init|startup/i
+            { event: "SessionStart", matcher: nil }
+          else
+            # Default to PostToolUse for unknown custom hooks and post_tool patterns
+            { event: "PostToolUse", matcher: nil }
+          end
+        end
       end
     end
   end

data/lib/aircana/cli/commands/project.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "json"
+require "tty-prompt"
+require_relative "../../symlink_manager"
+require_relative "../../generators/project_config_generator"
+
+module Aircana
+  module CLI
+    module Project
+      class << self
+        def init
+          generator = Aircana::Generators::ProjectConfigGenerator.new
+          config_path = generator.generate
+
+          Aircana.human_logger.success "Initialized project.json at #{config_path}"
+          Aircana.human_logger.info "Add folders using: aircana project add <path>"
+        end
+
+        def add(folder_path)
+          project_json_path = File.join(Aircana.configuration.project_dir, ".aircana", "project.json")
+
+          # Create project.json if it doesn't exist
+          init unless File.exist?(project_json_path)
+
+          # Validate folder exists
+          full_path = File.join(Aircana.configuration.project_dir, folder_path)
+          unless Dir.exist?(full_path)
+            Aircana.human_logger.error "Folder not found: #{folder_path}"
+            return
+          end
+
+          # Load existing config
+          config = JSON.parse(File.read(project_json_path))
+          config["folders"] ||= []
+
+          # Check if folder already exists
+          if config["folders"].any? { |f| f["path"] == folder_path }
+            Aircana.human_logger.warn "Folder already configured: #{folder_path}"
+            return
+          end
+
+          # Add the folder
+          config["folders"] << { "path" => folder_path }
+
+          # Save updated config
+          File.write(project_json_path, JSON.pretty_generate(config))
+
+          Aircana.human_logger.success "Added folder: #{folder_path}"
+
+          # Check what agents/knowledge would be available
+          check_folder_contents(folder_path)
+
+          # Offer to sync
+          prompt = TTY::Prompt.new
+          sync if prompt.yes?("Would you like to sync symlinks now?")
+        end
+
+        def remove(folder_path)
+          project_json_path = File.join(Aircana.configuration.project_dir, ".aircana", "project.json")
+
+          unless File.exist?(project_json_path)
+            Aircana.human_logger.error "No project.json found. Run 'aircana project init' first."
+            return
+          end
+
+          # Load existing config
+          config = JSON.parse(File.read(project_json_path))
+          config["folders"] ||= []
+
+          # Remove the folder
+          original_count = config["folders"].size
+          config["folders"].reject! { |f| f["path"] == folder_path }
+
+          if config["folders"].size == original_count
+            Aircana.human_logger.warn "Folder not found in configuration: #{folder_path}"
+            return
+          end
+
+          # Save updated config
+          File.write(project_json_path, JSON.pretty_generate(config))
+
+          Aircana.human_logger.success "Removed folder: #{folder_path}"
+
+          # Clean up symlinks
+          Aircana::SymlinkManager.cleanup_broken_symlinks
+        end
+
+        def list
+          project_json_path = File.join(Aircana.configuration.project_dir, ".aircana", "project.json")
+
+          unless File.exist?(project_json_path)
+            Aircana.human_logger.info "No project.json found. Run 'aircana project init' to create one."
+            return
+          end
+
+          config = JSON.parse(File.read(project_json_path))
+          folders = config["folders"] || []
+
+          if folders.empty?
+            Aircana.human_logger.info "No folders configured."
+            Aircana.human_logger.info "Add folders using: aircana project add <path>"
+            return
+          end
+
+          Aircana.human_logger.info "Configured folders:"
+          folders.each do |folder|
+            folder_path = folder["path"]
+            status = Dir.exist?(File.join(Aircana.configuration.project_dir, folder_path)) ? "✓" : "✗"
+            Aircana.human_logger.info "  #{status} #{folder_path}"
+
+            # Show available agents if folder exists
+            check_folder_contents(folder_path, indent: "    ") if status == "✓"
+          end
+        end
+
+        def sync
+          Aircana.human_logger.info "Syncing multi-root project symlinks..."
+
+          stats = Aircana::SymlinkManager.sync_multi_root_agents
+
+          if stats[:agents].zero? && stats[:knowledge].zero?
+            Aircana.human_logger.info "No agents or knowledge bases to link."
+          else
+            Aircana.human_logger.success "Sync complete: #{stats[:agents]} agents, #{stats[:knowledge]} knowledge bases"
+          end
+        end
+
+        private
+
+        def check_folder_contents(folder_path, indent: "  ")
+          agents_dir = File.join(folder_path, ".claude", "agents")
+          knowledge_dir = File.join(folder_path, ".aircana", "agents")
+
+          agents = []
+          knowledge = []
+
+          agents = Dir.glob("#{agents_dir}/*.md").map { |f| File.basename(f, ".md") } if Dir.exist?(agents_dir)
+
+          if Dir.exist?(knowledge_dir)
+            knowledge = Dir.glob("#{knowledge_dir}/*").select { |d| File.directory?(d) }
+                           .map { |d| File.basename(d) }
+          end
+
+          Aircana.human_logger.info "#{indent}Agents: #{agents.join(", ")}" if agents.any?
+
+          Aircana.human_logger.info "#{indent}Knowledge: #{knowledge.join(", ")}" if knowledge.any?
+
+          return unless agents.empty? && knowledge.empty?
+
+          Aircana.human_logger.info "#{indent}No agents or knowledge found"
+        end
+      end
+    end
+  end
+end

data/lib/aircana/cli/help_formatter.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Aircana
+  module CLI
+    # Custom help formatter to organize commands into logical groups
+    module HelpFormatter
+      def help(command = nil, subcommand: false)
+        if command
+          super
+        else
+          print_grouped_commands
+        end
+      end
+
+      private
+
+      def print_grouped_commands
+        say "Aircana - Context Management for Claude Code", :bold
+        command_groups.each { |group_name, commands| print_command_group(group_name, commands) }
+        say
+        say "Use 'aircana help [COMMAND]' for more information on a specific command.", :green
+      end
+
+      def command_groups
+        {
+          "File Management" => %w[files],
+          "Agent Management" => %w[agents],
+          "Hook Management" => %w[hooks],
+          "Project Management" => %w[project],
+          "System" => %w[generate install doctor dump-context]
+        }
+      end
+
+      def print_command_group(group_name, group_commands)
+        print_group_header(group_name)
+        group_commands.each { |cmd_name| print_group_command(cmd_name) }
+      end
+
+      def print_group_header(group_name)
+        say
+        say "#{group_name}:", :yellow
+      end
+
+      def print_group_command(cmd_name)
+        cmd = self.class.commands[cmd_name]
+        return unless cmd
+
+        if subcommand?(cmd_name)
+          print_subcommand_group(cmd_name, cmd)
+        else
+          print_command(cmd)
+        end
+      end
+
+      def subcommand?(cmd_name)
+        %w[files agents hooks project].include?(cmd_name)
+      end
+
+      def print_subcommand_group(subcommand_name, cmd)
+        subcommand_class = get_subcommand_class(subcommand_name)
+        return print_command(cmd) unless subcommand_class
+
+        print_subcommands(subcommand_class, subcommand_name)
+      end
+
+      def get_subcommand_class(subcommand_name)
+        class_name = "#{subcommand_name.capitalize}Subcommand"
+        return self.class.const_get(class_name) if self.class.const_defined?(class_name)
+
+        nil
+      rescue NameError
+        nil
+      end
+
+      def print_subcommands(subcommand_class, subcommand_name)
+        subcommand_class.commands.each_value do |sub_cmd|
+          usage = "aircana #{subcommand_name} #{sub_cmd.usage}"
+          desc = sub_cmd.description
+          say "  #{usage.ljust(35)} # #{desc}"
+        end
+      end
+
+      def print_command(cmd)
+        usage = "aircana #{cmd.usage}"
+        desc = cmd.description
+        say "  #{usage.ljust(35)} # #{desc}"
+      end
+    end
+  end
+end

data/lib/aircana/cli/subcommand.rb

@@ -10,7 +10,8 @@ module Aircana
       end
 
       def self.subcommand_prefix
-        name.gsub(/.*::/, "").gsub(/^[A-Z]/) do |match|
+        # Extract the main command name from class name (e.g., "FilesSubcommand" -> "files")
+        name.gsub(/.*::/, "").gsub(/Subcommand$/, "").gsub(/^[A-Z]/) do |match|
           match[0].downcase
         end.gsub(/[A-Z]/) { |match| "-#{match[0].downcase}" } # rubocop:disable Style/MultilineBlockChain
       end

data/lib/aircana/configuration.rb

@@ -4,7 +4,7 @@ module Aircana
   class Configuration
     attr_accessor :global_dir, :project_dir, :relevant_project_files_dir, :stream, :output_dir,
                   :claude_code_config_path, :claude_code_project_config_path, :agent_knowledge_dir,
-                  :confluence_base_url, :confluence_username, :confluence_api_token
+                  :hooks_dir, :confluence_base_url, :confluence_username, :confluence_api_token
 
     def initialize
       setup_directory_paths
@@ -21,6 +21,7 @@ module Aircana
       @relevant_project_files_dir = File.join(@project_dir, ".aircana", "relevant_files")
       @output_dir = File.join(@global_dir, "aircana.out")
       @agent_knowledge_dir = File.join(@project_dir, ".aircana", "agents")
+      @hooks_dir = File.join(@project_dir, ".aircana", "hooks")
     end
 
     def setup_claude_code_paths

data/lib/aircana/contexts/confluence.rb

@@ -3,6 +3,7 @@
 require "httparty"
 require "reverse_markdown"
 require_relative "local"
+require_relative "manifest"
 require_relative "confluence_logging"
 require_relative "confluence_http"
 require_relative "confluence_content"
@@ -28,10 +29,36 @@ module Aircana
         setup_httparty
 
         pages = search_and_log_pages(agent)
-        return 0 if pages.empty?
+        return { pages_count: 0, sources: [] } if pages.empty?
 
-        process_pages(pages, agent)
-        pages.size
+        sources = process_pages_with_manifest(pages, agent)
+        create_or_update_manifest(agent, sources)
+
+        { pages_count: pages.size, sources: sources }
+      end
+
+      def refresh_from_manifest(agent:)
+        sources = Manifest.sources_from_manifest(agent)
+        return { pages_count: 0, sources: [] } if sources.empty?
+
+        validate_configuration!
+        setup_httparty
+
+        confluence_sources = sources.select { |s| s["type"] == "confluence" }
+        return { pages_count: 0, sources: [] } if confluence_sources.empty?
+
+        all_pages = []
+        confluence_sources.each do |source|
+          pages = fetch_pages_from_source(source)
+          all_pages.concat(pages)
+        end
+
+        return { pages_count: 0, sources: [] } if all_pages.empty?
+
+        updated_sources = process_pages_with_manifest(all_pages, agent)
+        Manifest.update_manifest(agent, updated_sources)
+
+        { pages_count: all_pages.size, sources: updated_sources }
       end
 
       def search_and_log_pages(agent)
@@ -48,8 +75,54 @@ module Aircana
         end
       end
 
+      def process_pages_with_manifest(pages, agent)
+        page_metadata = []
+
+        ProgressTracker.with_batch_progress(pages, "Processing pages") do |page, _index|
+          store_page_as_markdown(page, agent)
+          page_metadata << extract_page_metadata(page)
+        end
+
+        build_source_metadata(agent, page_metadata)
+      end
+
       private
 
+      def fetch_pages_from_source(source)
+        case source["type"]
+        when "confluence"
+          fetch_pages_by_label(source["label"])
+        else
+          []
+        end
+      end
+
+      def extract_page_metadata(page)
+        {
+          "id" => page["id"],
+          "title" => page["title"],
+          "last_updated" => page.dig("version", "when") || Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+        }
+      end
+
+      def build_source_metadata(agent, page_metadata)
+        [
+          {
+            "type" => "confluence",
+            "label" => agent,
+            "pages" => page_metadata
+          }
+        ]
+      end
+
+      def create_or_update_manifest(agent, sources)
+        if Manifest.manifest_exists?(agent)
+          Manifest.update_manifest(agent, sources)
+        else
+          Manifest.create_manifest(agent, sources)
+        end
+      end
+
       def validate_configuration!
         config = Aircana.configuration
 

data/lib/aircana/contexts/manifest.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Aircana
+  module Contexts
+    class Manifest
+      class << self
+        def create_manifest(agent, sources)
+          validate_sources(sources)
+
+          manifest_path = manifest_path_for(agent)
+          manifest_data = build_manifest_data(agent, sources)
+
+          FileUtils.mkdir_p(File.dirname(manifest_path))
+          File.write(manifest_path, JSON.pretty_generate(manifest_data))
+
+          Aircana.human_logger.info "Created knowledge manifest for agent '#{agent}'"
+          manifest_path
+        end
+
+        def update_manifest(agent, sources)
+          validate_sources(sources)
+
+          manifest_path = manifest_path_for(agent)
+
+          if File.exist?(manifest_path)
+            existing_data = JSON.parse(File.read(manifest_path))
+            manifest_data = existing_data.merge({
+                                                  "last_updated" => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+                                                  "sources" => sources
+                                                })
+          else
+            manifest_data = build_manifest_data(agent, sources)
+          end
+
+          FileUtils.mkdir_p(File.dirname(manifest_path))
+          File.write(manifest_path, JSON.pretty_generate(manifest_data))
+          manifest_path
+        end
+
+        def read_manifest(agent)
+          manifest_path = manifest_path_for(agent)
+          return nil unless File.exist?(manifest_path)
+
+          begin
+            manifest_data = JSON.parse(File.read(manifest_path))
+            validate_manifest(manifest_data)
+            manifest_data
+          rescue JSON::ParserError => e
+            Aircana.human_logger.warn "Invalid manifest for agent '#{agent}': #{e.message}"
+            nil
+          rescue ManifestError => e
+            Aircana.human_logger.warn "Manifest validation failed for agent '#{agent}': #{e.message}"
+            nil
+          end
+        end
+
+        def sources_from_manifest(agent)
+          manifest = read_manifest(agent)
+          return [] unless manifest
+
+          manifest["sources"] || []
+        end
+
+        def manifest_exists?(agent)
+          File.exist?(manifest_path_for(agent))
+        end
+
+        private
+
+        def manifest_path_for(agent)
+          resolved_agent_path = resolve_agent_path(agent)
+          File.join(resolved_agent_path, "manifest.json")
+        end
+
+        def resolve_agent_path(agent)
+          base_path = File.join(Aircana.configuration.agent_knowledge_dir, agent)
+
+          # If this is a symlink (multi-root scenario), resolve to original
+          if File.symlink?(base_path)
+            File.readlink(base_path)
+          else
+            base_path
+          end
+        end
+
+        def build_manifest_data(agent, sources)
+          timestamp = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+          {
+            "version" => "1.0",
+            "agent" => agent,
+            "created" => timestamp,
+            "last_updated" => timestamp,
+            "sources" => sources
+          }
+        end
+
+        def validate_manifest(manifest_data)
+          required_fields = %w[version agent sources]
+
+          required_fields.each do |field|
+            raise ManifestError, "Missing required field: #{field}" unless manifest_data.key?(field)
+          end
+
+          unless manifest_data["version"] == "1.0"
+            raise ManifestError, "Unsupported manifest version: #{manifest_data["version"]}"
+          end
+
+          validate_sources(manifest_data["sources"])
+        end
+
+        def validate_sources(sources)
+          raise ManifestError, "Sources must be an array" unless sources.is_a?(Array)
+
+          sources.each do |source|
+            validate_source(source)
+          end
+        end
+
+        def validate_source(source)
+          raise ManifestError, "Each source must be a hash" unless source.is_a?(Hash)
+
+          raise ManifestError, "Source missing required field: type" unless source.key?("type")
+
+          case source["type"]
+          when "confluence"
+            validate_confluence_source(source)
+          else
+            raise ManifestError, "Unknown source type: #{source["type"]}"
+          end
+        end
+
+        def validate_confluence_source(source)
+          raise ManifestError, "Confluence source missing required field: label" unless source.key?("label")
+
+          return unless source.key?("pages") && !source["pages"].is_a?(Array)
+
+          raise ManifestError, "Confluence pages must be an array"
+        end
+      end
+    end
+
+    class ManifestError < StandardError; end
+  end
+end

data/lib/aircana/generators/agents_generator.rb

@@ -68,7 +68,7 @@ module Aircana
       end
 
       def knowledge_path
-        ".aircana/agents/#{agent_name}/knowledge"
+        ".aircana/agents/#{agent_name}/knowledge/"
       end
     end
   end