octo-agent 0.11.2

data/lib/octo/utils/parser_manager.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+
+module Octo
+  module Utils
+    # Manages user-space parsers in ~/.octo/parsers/.
+    #
+    # On first use, default parser scripts are copied from the gem's
+    # default_parsers/ directory into ~/.octo/parsers/. After that,
+    # the user-space version is always used — allowing the LLM to modify
+    # or extend parsers without touching the gem itself.
+    #
+    # CLI interface contract (all parsers must follow):
+    #   ruby <parser>.rb <file_path>
+    #   stdout → extracted text (UTF-8)
+    #   stderr → error messages
+    #   exit 0 → success
+    #   exit 1 → failure
+    module ParserManager
+      PARSERS_DIR         = File.expand_path("~/.octo/parsers").freeze
+      DEFAULT_PARSERS_DIR = File.expand_path("../default_parsers", __dir__).freeze
+
+      PARSER_FOR = {
+        ".pdf"  => "pdf_parser.rb",
+        ".doc"  => "doc_parser.rb",
+        ".docx" => "docx_parser.rb",
+        ".xlsx" => "xlsx_parser.rb",
+        ".xls"  => "xlsx_parser.rb",
+        ".pptx" => "pptx_parser.rb",
+        ".ppt"  => "pptx_parser.rb",
+      }.freeze
+
+      # Ensure ~/.octo/parsers/ exists and all default parsers are present.
+      # Called at Agent startup (idempotent — safe to run every time).
+      #
+      # Copies every file from default_parsers/ (not just the entry-point .rb
+      # scripts listed in PARSER_FOR). A parser may ship companion helper
+      # scripts — e.g. pdf_parser_ocr.py sits next to pdf_parser.rb and is
+      # invoked by relative path — so those helpers must be distributed too.
+      #
+      # Version upgrade policy:
+      #   Each bundled parser declares `VERSION: <n>` in a header comment
+      #   (works for Ruby `# VERSION: 2` and Python `# VERSION: 2` alike,
+      #   scanned in the first 40 lines of the file).
+      #
+      #   On startup, per-file:
+      #     - If the file does NOT exist in ~/.octo/parsers/ → copy it.
+      #     - If it exists:
+      #         * bundled has no VERSION → never touch (bundled file
+      #           is opting out of managed upgrades).
+      #         * installed has no VERSION → treat it as legacy v0 and
+      #           upgrade (lenient mode — covers users who installed before
+      #           the VERSION scheme existed). The old file is backed up.
+      #         * both have VERSION, bundled > installed → upgrade, backing
+      #           up the old copy as `<script>.v<old>.bak`.
+      #         * bundled ≤ installed → leave the user's copy alone
+      #           (preserves LLM/user modifications).
+      #
+      #   Backups live alongside the parser so the user can inspect
+      #   their own edits after an upgrade. They are never removed
+      #   automatically.
+      def self.setup!
+        FileUtils.mkdir_p(PARSERS_DIR)
+
+        Dir.glob(File.join(DEFAULT_PARSERS_DIR, "**", "*")).each do |src|
+          next unless File.file?(src)
+          basename = File.basename(src)
+          next if basename.start_with?(".") || basename.end_with?(".bak")
+
+          rel  = src.sub(/^#{Regexp.escape(DEFAULT_PARSERS_DIR)}\/?/, "")
+          dest = File.join(PARSERS_DIR, rel)
+
+          if !File.exist?(dest)
+            FileUtils.mkdir_p(File.dirname(dest))
+            FileUtils.cp(src, dest)
+            # Preserve executable bit so sibling scripts can be run directly.
+            FileUtils.chmod(File.stat(src).mode, dest)
+            next
+          end
+
+          bundled_version = extract_version(src)
+          # Bundled file opts out of managed upgrades — never touch user copy.
+          next unless bundled_version
+
+          installed_version = extract_version(dest) || 0
+
+          if bundled_version > installed_version
+            backup = "#{dest}.v#{installed_version}.bak"
+            FileUtils.cp(dest, backup) unless File.exist?(backup)
+            FileUtils.cp(src, dest)
+            FileUtils.chmod(File.stat(src).mode, dest)
+          end
+        end
+      end
+
+      # Read the VERSION marker from a parser script (e.g. "# VERSION: 2").
+      # Works for any script language that uses `#` for comments
+      # (Ruby, Python, shell). Returns Integer or nil.
+      def self.extract_version(path)
+        return nil unless File.exist?(path)
+        # Only scan the first 40 lines — the marker lives in the header.
+        File.foreach(path).with_index do |line, i|
+          break if i >= 40
+          if (m = line.match(/^\s*#\s*VERSION:\s*(\d+)/i))
+            return m[1].to_i
+          end
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
+      # Run the appropriate parser for the given file path.
+      #
+      # @param file_path [String] path to the file to parse
+      # @return [Hash] { success: bool, text: String, error: String, parser_path: String }
+      def self.parse(file_path)
+        ext = File.extname(file_path.to_s).downcase
+        script = PARSER_FOR[ext]
+
+        unless script
+          return { success: false, text: nil,
+                   error: "No parser available for #{ext} files",
+                   parser_path: nil }
+        end
+
+        parser_path = File.join(PARSERS_DIR, script)
+
+        unless File.exist?(parser_path)
+          return { success: false, text: nil,
+                   error: "Parser not found: #{parser_path}",
+                   parser_path: parser_path }
+        end
+
+        raw_stdout, raw_stderr, status = Open3.capture3(RbConfig.ruby, parser_path, file_path)
+
+        # capture3 returns ASCII-8BIT across the subprocess boundary on Ruby 2.6+.
+        # Normalise both streams to UTF-8 immediately so all downstream code is clean.
+        stdout = Octo::Utils::Encoding.to_utf8(raw_stdout)
+        stderr = Octo::Utils::Encoding.to_utf8(raw_stderr)
+
+        # Filter out Ruby/Bundler version warnings that pollute stderr
+        clean_stderr = stderr.lines.reject { |l| l.match?(/warning:|already initialized constant/) }.join.strip
+
+        if status.success? && stdout.strip.length > 0
+          { success: true, text: stdout.strip, error: nil, parser_path: parser_path }
+        else
+          { success: false, text: nil,
+            error: clean_stderr.empty? ? "Parser exited with code #{status.exitstatus}" : clean_stderr,
+            parser_path: parser_path }
+        end
+      end
+
+      # Returns the path to a parser script for a given extension.
+      # Used by agent to tell LLM where to find/modify the parser.
+      def self.parser_path_for(ext)
+        script = PARSER_FOR[ext.downcase]
+        return nil unless script
+        File.join(PARSERS_DIR, script)
+      end
+    end
+  end
+end

data/lib/octo/utils/path_helper.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Octo
+  module Utils
+    module PathHelper
+      # Safely get basename from path, return placeholder if path is nil
+      def self.safe_basename(path, placeholder: "?")
+        return placeholder if path.nil? || path.to_s.empty?
+        File.basename(path.to_s)
+      rescue StandardError
+        placeholder
+      end
+    end
+  end
+end

data/lib/octo/utils/scripts_manager.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Octo
+  module Utils
+    # Manages user-space shell scripts in ~/.octo/scripts/.
+    #
+    # On first use, bundled scripts are copied from the gem's scripts/
+    # directory into ~/.octo/scripts/. The user-space copy is always
+    # used so users can customise scripts without modifying the gem.
+    #
+    # Bundled scripts are re-copied when the gem is upgraded (detected
+    # via gem version stamp in ~/.octo/scripts/.version).
+    module ScriptsManager
+      SCRIPTS_DIR         = File.expand_path("~/.octo/scripts").freeze
+      DEFAULT_SCRIPTS_DIR = File.expand_path("../../../scripts", __dir__).freeze
+      VERSION_FILE        = File.join(SCRIPTS_DIR, ".version").freeze
+
+      SCRIPTS = %w[
+        install_browser.sh
+        install_system_deps.sh
+        install_rails_deps.sh
+      ].freeze
+
+      # Copy bundled scripts to ~/.octo/scripts/ if missing or outdated.
+      # Called once at agent startup — fast (no-op after first run).
+      def self.setup!
+        FileUtils.mkdir_p(SCRIPTS_DIR)
+
+        current_version = Octo::VERSION
+        stored_version  = File.exist?(VERSION_FILE) ? File.read(VERSION_FILE).strip : nil
+
+        SCRIPTS.each do |script|
+          dest = File.join(SCRIPTS_DIR, script)
+          src  = File.join(DEFAULT_SCRIPTS_DIR, script)
+          next unless File.exist?(src)
+
+          # Copy if missing or gem was upgraded
+          if !File.exist?(dest) || stored_version != current_version
+            FileUtils.cp(src, dest)
+            FileUtils.chmod(0o755, dest)
+          end
+        end
+
+        # Write version stamp after successful copy
+        File.write(VERSION_FILE, current_version)
+      end
+
+      # Returns the full path to a managed script.
+      # @param name [String] script filename, e.g. "install_browser.sh"
+      # @return [String, nil]
+      def self.path_for(name)
+        dest = File.join(SCRIPTS_DIR, name)
+        File.exist?(dest) ? dest : nil
+      end
+    end
+  end
+end

data/lib/octo/utils/string_matcher.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Octo
+  module Utils
+    # Utilities for finding and matching strings in file content.
+    # Used by the Edit tool and edit preview to apply a consistent
+    # layered matching strategy: exact → trim → unescape → smart line match.
+    module StringMatcher
+      # Find a matching string in content using a layered strategy.
+      #
+      # Strategy (applied in order):
+      #   1. Exact match (original old_string)
+      #   2. Trimmed match (leading/trailing whitespace stripped)
+      #   3. Unescaped match (over-escaped sequences normalised)
+      #   4. Combined trim + unescape
+      #   5. Smart line-by-line match (tolerates indent differences)
+      #
+      # @param content [String] File content to search in
+      # @param old_string [String] String to locate
+      # @return [Hash, nil] { matched_string: String, occurrences: Integer }
+      #   or nil when nothing matches
+      def self.find_match(content, old_string)
+        # Defensive: if either side contains invalid UTF-8 bytes (binary files,
+        # mixed-encoding content, etc.), Regexp#scan / String#include? with a
+        # UTF-8-tagged candidate can raise `ArgumentError: invalid byte sequence
+        # in UTF-8`. Scrub once at the entry point so every matching layer —
+        # including callers like the edit preview — is safe.
+        content    = Octo::Utils::Encoding.to_utf8(content)    unless content.nil?
+        old_string = Octo::Utils::Encoding.to_utf8(old_string) unless old_string.nil?
+
+        candidates = generate_candidates(old_string)
+
+        # Simple string matching for each candidate
+        candidates.each do |candidate|
+          next if candidate.empty?
+
+          if content.include?(candidate)
+            return {
+              matched_string: candidate,
+              occurrences: count_occurrences(content, candidate)
+            }
+          end
+        end
+
+        # Fall back to smart line-by-line matching (tabs vs spaces, etc.)
+        try_smart_match(content, old_string)
+      end
+
+      # Count non-overlapping occurrences of `needle` in `haystack` without
+      # going through Regexp (safer on mixed-encoding strings and avoids an
+      # extra escape step).
+      def self.count_occurrences(haystack, needle)
+        return 0 if needle.empty?
+        count = 0
+        offset = 0
+        while (idx = haystack.index(needle, offset))
+          count += 1
+          offset = idx + needle.length
+        end
+        count
+      end
+
+      # Generate candidate strings by applying different transformations.
+      #
+      # @param old_string [String]
+      # @return [Array<String>] Unique list of candidates
+      def self.generate_candidates(old_string)
+        trimmed           = old_string.strip
+        unescaped         = unescape_over_escaped(old_string)
+        unescaped_trimmed = unescape_over_escaped(trimmed)
+
+        [
+          old_string,        # Original
+          trimmed,           # Trim leading/trailing whitespace
+          unescaped,         # Unescape over-escaped sequences
+          unescaped_trimmed  # Combined: trim + unescape
+        ].uniq
+      end
+
+      # Convert over-escaped sequences back to their real characters.
+      # This handles the common case where LLMs double-escape backslashes.
+      #
+      # @param str [String]
+      # @return [String]
+      def self.unescape_over_escaped(str)
+        result = str.dup
+
+        # Unicode escapes: \uXXXX → actual Unicode character
+        result = result.gsub(/\\u([0-9a-fA-F]{4})/) { [$1.hex].pack("U") }
+
+        # Common escape sequences
+        result = result.gsub('\\n',  "\n")
+        result = result.gsub('\\t',  "\t")
+        result = result.gsub('\\r',  "\r")
+        result = result.gsub('\\f',  "\f")
+        result = result.gsub('\\b',  "\b")
+        result = result.gsub('\\v',  "\v")
+        result = result.gsub('\\"',  '"')
+        result = result.gsub('\\\\', "\\")
+
+        result
+      end
+
+      # Try smart line-by-line matching that tolerates leading whitespace differences.
+      #
+      # @param content [String]
+      # @param old_string [String]
+      # @return [Hash, nil]
+      def self.try_smart_match(content, old_string)
+        candidates = generate_candidates(old_string)
+
+        candidates.each do |candidate|
+          next if candidate.empty?
+
+          candidate_lines = candidate.lines
+          next if candidate_lines.empty?
+
+          content_lines = content.lines
+          matches = []
+
+          (0..content_lines.length - candidate_lines.length).each do |start_idx|
+            slice = content_lines[start_idx, candidate_lines.length]
+            next unless slice
+
+            if lines_match_normalized?(slice, candidate_lines)
+              matches << { start: start_idx, matched_string: slice.join }
+            end
+          end
+
+          unless matches.empty?
+            return {
+              matched_string: matches.first[:matched_string],
+              occurrences: matches.length
+            }
+          end
+        end
+
+        nil
+      end
+
+      # Compare two arrays of lines after normalising leading whitespace.
+      #
+      # @param lines1 [Array<String>]
+      # @param lines2 [Array<String>]
+      # @return [Boolean]
+      def self.lines_match_normalized?(lines1, lines2)
+        return false unless lines1.length == lines2.length
+
+        lines1.zip(lines2).all? do |line1, line2|
+          norm1 = line1.sub(/^\s+/, " ").chomp
+          norm2 = line2.sub(/^\s+/, " ").chomp
+
+          norm1 == norm2 || norm1 == unescape_over_escaped(norm2)
+        end
+      end
+    end
+  end
+end

data/lib/octo/utils/trash_directory.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+
+module Octo
+  # Manages global trash directory at ~/.octo/trash
+  # Organizes trash by project directory using path hash
+  class TrashDirectory
+    GLOBAL_TRASH_ROOT = File.join(Dir.home, ".octo", "trash")
+
+    attr_reader :project_root, :trash_dir, :backup_dir
+
+    def initialize(project_root = Dir.pwd)
+      @project_root = File.expand_path(project_root)
+      @project_hash = generate_project_hash(@project_root)
+      @trash_dir = File.join(GLOBAL_TRASH_ROOT, @project_hash)
+      @backup_dir = File.join(@trash_dir, "backups")
+      
+      setup_directories
+    end
+
+    # Generate a unique hash for project path
+    def generate_project_hash(path)
+      # Use MD5 hash of the absolute path, take first 16 chars for readability
+      hash = Digest::MD5.hexdigest(path)[0..15]
+      # Also include a readable suffix based on project name
+      project_name = File.basename(path).gsub(/[^a-zA-Z0-9_-]/, '_')[0..20]
+      "#{hash}_#{project_name}"
+    end
+
+    # Setup trash and backup directories with proper structure
+    def setup_directories
+      [@trash_dir, @backup_dir].each do |dir|
+        FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+
+        # Create .gitignore file to avoid trash files being committed
+        gitignore_path = File.join(dir, '.gitignore')
+        unless File.exist?(gitignore_path)
+          File.write(gitignore_path, "*\n!.gitignore\n")
+        end
+      end
+
+      # Create project metadata file
+      create_project_metadata
+    end
+
+    # Create or update metadata about this project
+    def create_project_metadata
+      metadata_file = File.join(@trash_dir, '.project_metadata.json')
+      
+      metadata = {
+        project_root: @project_root,
+        project_name: File.basename(@project_root),
+        project_hash: @project_hash,
+        created_at: File.exist?(metadata_file) ? JSON.parse(File.read(metadata_file))['created_at'] : Time.now.iso8601,
+        last_accessed: Time.now.iso8601
+      }
+      
+      File.write(metadata_file, JSON.pretty_generate(metadata))
+    rescue StandardError => e
+      # Log warning but don't block operation
+      warn "Warning: Could not create project metadata: #{e.message}"
+    end
+
+    # Get all project directories that have trash
+    def self.all_projects
+      return [] unless Dir.exist?(GLOBAL_TRASH_ROOT)
+      
+      projects = []
+      Dir.glob(File.join(GLOBAL_TRASH_ROOT, "*", ".project_metadata.json")).each do |metadata_file|
+        begin
+          metadata = JSON.parse(File.read(metadata_file))
+          projects << {
+            project_root: metadata['project_root'],
+            project_name: metadata['project_name'],
+            project_hash: metadata['project_hash'],
+            trash_dir: File.dirname(metadata_file),
+            last_accessed: metadata['last_accessed']
+          }
+        rescue StandardError
+          # Skip corrupted metadata
+        end
+      end
+      
+      projects.sort_by { |p| p[:last_accessed] }.reverse
+    end
+
+    # Get trash directory for a specific project
+    def self.for_project(project_root)
+      new(project_root)
+    end
+
+    # Clean up trash directories for non-existent projects
+    def self.cleanup_orphaned_projects
+      return 0 unless Dir.exist?(GLOBAL_TRASH_ROOT)
+      
+      cleaned_count = 0
+      all_projects.each do |project|
+        unless Dir.exist?(project[:project_root])
+          # Project no longer exists, optionally remove trash
+          # For safety, we'll just mark it as orphaned
+          orphan_file = File.join(project[:trash_dir], '.orphaned')
+          File.write(orphan_file, "Original project path no longer exists: #{project[:project_root]}\n")
+          cleaned_count += 1
+        end
+      end
+      
+      cleaned_count
+    end
+  end
+end

data/lib/octo/utils/workspace_rules.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Octo
+  module Utils
+    # Discovers .octorules files in the workspace.
+    # Used by both SystemPromptBuilder (rules injection) and WelcomeBanner (UI display).
+    module WorkspaceRules
+      RULES_FILENAMES = [".octorules", ".cursorrules", "CLAUDE.md"].freeze
+      SUB_PROJECT_SUMMARY_LINES = 5
+
+      # Find the main rules file in the given directory.
+      # @param dir [String] Directory to search
+      # @return [Hash, nil] { path:, name:, content: } or nil
+      def self.find_main(dir)
+        RULES_FILENAMES.each do |filename|
+          path = File.join(dir, filename)
+          next unless File.exist?(path)
+
+          content = File.read(path).strip
+          return { path: path, name: filename, content: content } unless content.empty?
+        end
+        nil
+      end
+
+      # Find all sub-project .octorules in immediate subdirectories.
+      # @param dir [String] Parent directory to scan
+      # @return [Array<Hash>] Array of { sub_name:, relative_path:, content:, summary: }
+      def self.find_sub_projects(dir)
+        Dir.glob(File.join(dir, "*", ".octorules")).sort.filter_map do |rules_path|
+          content = File.read(rules_path).strip
+          next if content.empty?
+
+          sub_name = File.basename(File.dirname(rules_path))
+          summary = content.lines.first(SUB_PROJECT_SUMMARY_LINES).map(&:chomp).join("\n")
+
+          {
+            sub_name: sub_name,
+            relative_path: "#{sub_name}/.octorules",
+            content: content,
+            summary: summary
+          }
+        end
+      end
+    end
+  end
+end

data/lib/octo/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Octo
+  VERSION = "0.11.2"
+end