anima-core 0.2.0 → 0.3.0

data/lib/providers/anthropic.rb

@@ -25,21 +25,11 @@ module Providers
     class ServerError < TransientError; end
 
     class << self
-      def validate!
-        token = fetch_token
-        validate_token_format!(token)
-        validate_token_api!(token)
-        true
-      end
-
       def fetch_token
         token = Rails.application.credentials.dig(:anthropic, :subscription_token)
         raise AuthenticationError, <<~MSG.strip if token.blank?
           No Anthropic subscription token found in credentials.
-          Run: bin/rails credentials:edit
-          Add:
-            anthropic:
-              subscription_token: sk-ant-oat01-YOUR_TOKEN_HERE
+          Use the TUI token setup (Ctrl+a → a) to configure your token.
         MSG
         token
       end
@@ -123,7 +113,7 @@ module Providers
         true
       when 401
         raise AuthenticationError,
-          "Token rejected by Anthropic API (401). Re-run `claude setup-token` and update credentials."
+          "Token rejected by Anthropic API (401). Re-run `claude setup-token` and use the TUI token setup (Ctrl+a → a)."
       when 403
         raise AuthenticationError,
           "Token not authorized for API access (403). This credential may be restricted to Claude Code only."
@@ -151,7 +141,7 @@ module Providers
         raise Error, "Bad request: #{error_message(response)}"
       when 401
         raise AuthenticationError,
-          "Authentication failed (401): #{error_message(response)}. Re-run `claude setup-token` and update credentials."
+          "Authentication failed (401): #{error_message(response)}. Re-run `claude setup-token` and use the TUI token setup (Ctrl+a → a)."
       when 403
         raise AuthenticationError,
           "Forbidden (403): #{error_message(response)}"

data/lib/tools/edit.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Tools
+  # Performs surgical text replacement with uniqueness constraint.
+  # Finds old_text in the file (must match exactly one location), replaces
+  # with new_text, and returns a unified diff. Falls back to
+  # whitespace-normalized fuzzy matching when exact match fails.
+  #
+  # Normalizes BOM and CRLF line endings for matching, restoring them after
+  # the edit. Rejects ambiguous edits where old_text matches zero or
+  # multiple locations.
+  #
+  # @example Replacing a method body
+  #   tool.execute("path" => "app.rb",
+  #                "old_text" => "def greet\n  'hi'\nend",
+  #                "new_text" => "def greet\n  'hello'\nend")
+  #   # => "--- app.rb\n+++ app.rb\n@@ -1,3 +1,3 @@\n ..."
+  class Edit < Base
+    MAX_FILE_SIZE = 10 * 1024 * 1024 # 10 MB
+
+    def self.tool_name = "edit"
+
+    def self.description = "Replace exact text in a file. old_text must match exactly one location; " \
+                           "include surrounding lines for uniqueness. Use for surgical edits; " \
+                           "use write for new files or full replacement."
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          path: {type: "string", description: "Absolute or relative file path (relative resolved against working directory)"},
+          old_text: {type: "string", description: "Exact text to find (must match exactly one location — include surrounding context if needed)"},
+          new_text: {type: "string", description: "Replacement text (empty string to delete)"}
+        },
+        required: %w[path old_text new_text]
+      }
+    end
+
+    # @param shell_session [ShellSession, nil] provides working directory for resolving relative paths
+    def initialize(shell_session: nil, **)
+      @working_directory = shell_session&.pwd
+    end
+
+    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API
+    # @return [String] unified diff showing the change
+    # @return [Hash] with :error key on failure
+    def execute(input)
+      path, old_text, new_text = extract_params(input)
+      return {error: "Path cannot be blank"} if path.empty?
+      return {error: "old_text cannot be blank"} if old_text.empty?
+
+      path = resolve_path(path)
+
+      error = validate_file(path)
+      return error if error
+
+      edit_file(path, old_text, new_text)
+    end
+
+    private
+
+    def extract_params(input)
+      path = input["path"].to_s.strip
+      old_text = input["old_text"].to_s
+      new_text = input["new_text"].to_s
+      [path, old_text, new_text]
+    end
+
+    def resolve_path(path)
+      if @working_directory
+        File.expand_path(path, @working_directory)
+      else
+        File.expand_path(path)
+      end
+    end
+
+    def validate_file(path)
+      return {error: "File not found: #{path}"} unless File.exist?(path)
+      return {error: "Is a directory: #{path}"} if File.directory?(path)
+      return {error: "Permission denied: #{path}"} unless File.readable?(path) && File.writable?(path)
+      size = File.size(path)
+      if size > MAX_FILE_SIZE
+        {error: "File is #{size} bytes (#{size / 1_048_576} MB). " \
+                "Max editable size is #{MAX_FILE_SIZE / 1_048_576} MB. Use bash tool with sed instead."}
+      end
+    end
+
+    def edit_file(path, old_text, new_text)
+      raw = File.binread(path)
+      bom = extract_bom(raw)
+      content = raw[bom.length..].force_encoding("UTF-8")
+      had_crlf = content.include?("\r\n")
+      normalized = had_crlf ? content.gsub("\r\n", "\n") : content
+
+      match = find_unique_match(normalized, old_text, path)
+      return match if match.is_a?(Hash)
+
+      position, matched_text, fuzzy = match
+      new_content = normalized[0...position] + new_text + normalized[(position + matched_text.length)..]
+
+      if normalized == new_content
+        return {error: "old_text and new_text are identical. No changes made to #{path}."}
+      end
+
+      output = had_crlf ? new_content.gsub("\n", "\r\n") : new_content
+      File.binwrite(path, bom + output.b)
+
+      build_diff(path, normalized, new_content, fuzzy)
+    rescue Errno::EACCES
+      {error: "Permission denied: #{path}"}
+    rescue Errno::ENOSPC
+      {error: "No space left on device: #{path}"}
+    rescue Errno::EROFS
+      {error: "Read-only file system: #{path}"}
+    end
+
+    # @return [String] UTF-8 BOM bytes if present, empty binary string otherwise
+    def extract_bom(raw)
+      bytes = raw.b
+      bytes.start_with?("\xEF\xBB\xBF".b) ? bytes[0, 3] : "".b
+    end
+
+    # Finds exactly one match for old_text in content.
+    # Tries exact match first, then whitespace-normalized fuzzy match.
+    # @return [Array(Integer, String, Boolean)] position, matched text, fuzzy flag
+    # @return [Hash] error hash if zero or multiple matches found
+    def find_unique_match(content, old_text, path)
+      exact = find_all_positions(content, old_text)
+      return [exact[0], old_text, false] if exact.one?
+      return ambiguity_error(exact, content, path) if exact.length > 1
+
+      fuzzy = find_fuzzy_matches(content, old_text)
+      return [fuzzy[0][0], fuzzy[0][1], true] if fuzzy.one?
+      return ambiguity_error(fuzzy.map(&:first), content, path, fuzzy: true) if fuzzy.length > 1
+
+      {error: "Could not find old_text in #{path}. " \
+              "Verify the text exists and matches exactly (including whitespace). " \
+              "Use the read tool to check current file contents."}
+    end
+
+    def ambiguity_error(positions, content, path, fuzzy: false)
+      kind = fuzzy ? "fuzzy matches" : "matches"
+      line_numbers = positions.map { |pos| line_number_at(content, pos) }
+      {error: "Found #{positions.length} #{kind} for old_text in #{path}. " \
+              "Provide more surrounding context to uniquely identify the location. " \
+              "Matches at lines: #{line_numbers.join(", ")}"}
+    end
+
+    def line_number_at(content, position)
+      content[0...position].count("\n") + 1
+    end
+
+    def find_all_positions(content, text)
+      positions = []
+      offset = 0
+      while (pos = content.index(text, offset))
+        positions << pos
+        offset = pos + 1
+      end
+      positions
+    end
+
+    # Finds old_text in content using whitespace-normalized line comparison.
+    # @return [Array<Array(Integer, String)>] array of [position, matched_text] pairs
+    def find_fuzzy_matches(content, old_text)
+      content_lines = content.split("\n", -1)
+      search_lines = old_text.split("\n", -1)
+      search_lines.pop if search_lines.last&.empty? && old_text.end_with?("\n")
+      trailing_newline = old_text.end_with?("\n")
+
+      normalized_search = search_lines.map { |line| collapse_whitespace(line) }
+      return [] if normalized_search.all?(&:empty?)
+
+      window_size = search_lines.length
+      matches = []
+      (0..content_lines.length - window_size).each do |start_idx|
+        window = content_lines[start_idx, window_size]
+        next unless window.map { |line| collapse_whitespace(line) } == normalized_search
+
+        pos = start_idx.zero? ? 0 : content_lines[0...start_idx].sum { |line| line.length + 1 }
+        matched = window.join("\n")
+        matched += "\n" if trailing_newline
+        matches << [pos, matched]
+      end
+
+      matches
+    end
+
+    def collapse_whitespace(text)
+      text.gsub(/[[:blank:]]+/, " ").strip
+    end
+
+    # Generates a unified diff between old and new content with 3 lines of context.
+    DIFF_CONTEXT = 3
+
+    def build_diff(path, old_content, new_content, fuzzy)
+      before = old_content.lines(chomp: true)
+      after = new_content.lines(chomp: true)
+
+      first = 0
+      first += 1 while first < before.length && first < after.length && before[first] == after[first]
+
+      old_end = before.length - 1
+      new_end = after.length - 1
+      while old_end > first && new_end > first && before[old_end] == after[new_end]
+        old_end -= 1
+        new_end -= 1
+      end
+
+      ctx_start = [first - DIFF_CONTEXT, 0].max
+      old_ctx_end = [old_end + DIFF_CONTEXT, before.length - 1].min
+      new_ctx_end = [new_end + DIFF_CONTEXT, after.length - 1].min
+
+      hunk = []
+      hunk << "--- #{path}"
+      hunk << "+++ #{path}"
+      hunk << "@@ -#{ctx_start + 1},#{old_ctx_end - ctx_start + 1} +#{ctx_start + 1},#{new_ctx_end - ctx_start + 1} @@"
+      (ctx_start...first).each { |idx| hunk << " #{before[idx]}" }
+      (first..old_end).each { |idx| hunk << "-#{before[idx]}" }
+      (first..new_end).each { |idx| hunk << "+#{after[idx]}" }
+      ((old_end + 1)..old_ctx_end).each { |idx| hunk << " #{before[idx]}" }
+
+      diff = hunk.join("\n")
+      fuzzy ? "(fuzzy match — whitespace differences were ignored)\n#{diff}" : diff
+    end
+  end
+end

data/lib/tools/read.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Tools
+  # Reads file contents with smart truncation and offset/limit paging.
+  # Returns plain text without line numbers, normalized to LF line endings.
+  #
+  # Truncation limits: `MAX_LINES` lines or `MAX_BYTES` bytes, whichever
+  # hits first. When truncated, appends a continuation hint with the next
+  # offset value so the agent can page through large files.
+  #
+  # @example Basic read
+  #   tool.execute("path" => "config/routes.rb")
+  #   # => "Rails.application.routes.draw do\n  ..."
+  #
+  # @example Paging through a large file
+  #   tool.execute("path" => "large.log", "offset" => 2001, "limit" => 500)
+  #   # => "line 2001 content\n..."
+  class Read < Base
+    MAX_LINES = 2_000
+    MAX_BYTES = 50_000
+
+    def self.tool_name = "read"
+
+    def self.description = "Read file contents. Returns plain text with smart truncation. Use offset/limit to page through large files."
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          path: {type: "string", description: "Absolute or relative file path (relative resolved against working directory)"},
+          offset: {type: "integer", description: "1-indexed line number to start from (default: 1)"},
+          limit: {type: "integer", description: "Maximum number of lines to read (default: 2000, also limited by #{MAX_BYTES} byte cap)"}
+        },
+        required: ["path"]
+      }
+    end
+
+    # @param shell_session [ShellSession, nil] provides working directory for resolving relative paths
+    def initialize(shell_session: nil, **)
+      @working_directory = shell_session&.pwd
+    end
+
+    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API
+    # @return [String] file contents (possibly truncated with continuation hint)
+    # @return [Hash] with :error key on failure
+    def execute(input)
+      path, offset, limit = extract_params(input)
+      return {error: "Path cannot be blank"} if path.empty?
+
+      path = resolve_path(path)
+
+      error = validate_file(path)
+      return error if error
+
+      read_file(path, offset, limit)
+    end
+
+    private
+
+    def extract_params(input)
+      path = input["path"].to_s.strip
+      offset = [input["offset"].to_i, 1].max
+      raw_limit = input["limit"]
+      limit = raw_limit ? [raw_limit.to_i, 1].max : MAX_LINES
+      [path, offset, limit]
+    end
+
+    def resolve_path(path)
+      if @working_directory
+        File.expand_path(path, @working_directory)
+      else
+        File.expand_path(path)
+      end
+    end
+
+    def validate_file(path)
+      return {error: "File not found: #{path}"} unless File.exist?(path)
+      return {error: "Is a directory: #{path}"} if File.directory?(path)
+      {error: "Permission denied: #{path}"} unless File.readable?(path)
+    end
+
+    # Reads the file, normalizes line endings, and applies truncation limits.
+    # Two limits are enforced as first-hit-wins: line count and byte size.
+    # A single line exceeding `MAX_BYTES` is rejected outright (likely minified).
+    # Files larger than `MAX_READ_SIZE` are rejected to avoid memory exhaustion.
+    MAX_READ_SIZE = 10 * 1024 * 1024 # 10 MB
+
+    def read_file(path, offset, limit)
+      file_size = File.size(path)
+      if file_size > MAX_READ_SIZE
+        return {error: "File is #{file_size} bytes (#{file_size / 1_048_576} MB). " \
+                       "Max readable size is #{MAX_READ_SIZE / 1_048_576} MB. " \
+                       "Use bash tool with: head -n #{offset + limit} #{path} | tail -n +#{offset}"}
+      end
+
+      lines = normalize(File.read(path))
+      return "" if lines.empty?
+
+      start_index = offset - 1
+      return "[File has #{lines.size} lines. Offset #{offset} is beyond end of file.]" if start_index >= lines.size
+
+      window = lines[start_index, [limit, MAX_LINES].min]
+
+      error = check_oversized_lines(window, offset, path)
+      return error if error
+
+      build_output(window, lines.size, offset)
+    end
+
+    def normalize(content)
+      content.gsub("\r\n", "\n").lines
+    end
+
+    def check_oversized_lines(window, offset, path)
+      index = window.index { |line| line.bytesize > MAX_BYTES }
+      return unless index
+
+      line_num = offset + index
+      {error: "Line #{line_num} exceeds #{MAX_BYTES} bytes (likely minified). " \
+              "Use bash tool with: sed -n '#{line_num}p' #{path}"}
+    end
+
+    def build_output(window, total_lines, offset)
+      text, count = accumulate_lines(window)
+      end_line = offset + count - 1
+
+      if end_line < total_lines
+        text + "\n\n[Showing lines #{offset}-#{end_line} of #{total_lines}. Use offset=#{end_line + 1} to continue.]"
+      else
+        text
+      end
+    end
+
+    # Accumulates lines until `MAX_BYTES` would be exceeded.
+    # @return [Array(String, Integer)] accumulated text and number of lines included
+    def accumulate_lines(window)
+      output = +""
+      bytes = 0
+      count = 0
+
+      window.each_with_index do |line, index|
+        break if bytes + line.bytesize > MAX_BYTES && index > 0
+
+        output << line
+        bytes += line.bytesize
+        count += 1
+      end
+
+      [output, count]
+    end
+  end
+end

data/lib/tools/write.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Tools
+  # Creates or overwrites files with automatic intermediate directory creation.
+  # Writes content exactly as given — no line ending normalization, no BOM
+  # handling. Full replacement only; no append or merge.
+  #
+  # @example Creating a new file
+  #   tool.execute("path" => "config/new.yml", "content" => "key: value\n")
+  #   # => "Wrote 11 bytes to /home/user/project/config/new.yml"
+  #
+  # @example Overwriting an existing file
+  #   tool.execute("path" => "README.md", "content" => "# Title\n")
+  #   # => "Wrote 9 bytes to /home/user/project/README.md"
+  class Write < Base
+    def self.tool_name = "write"
+
+    def self.description = "Create or overwrite a file. Creates intermediate directories automatically. Use for new files or full replacement."
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          path: {type: "string", description: "Absolute or relative file path (relative resolved against working directory)"},
+          content: {type: "string", description: "Full file content to write"}
+        },
+        required: %w[path content]
+      }
+    end
+
+    # @param shell_session [ShellSession, nil] provides working directory for resolving relative paths
+    def initialize(shell_session: nil, **)
+      @working_directory = shell_session&.pwd
+    end
+
+    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API
+    # @return [String] confirmation with bytes written and resolved path
+    # @return [Hash] with :error key on failure
+    def execute(input)
+      path, content = extract_params(input)
+      return {error: "Path cannot be blank"} if path.empty?
+
+      path = resolve_path(path)
+
+      error = validate_target(path)
+      return error if error
+
+      write_file(path, content)
+    end
+
+    private
+
+    def extract_params(input)
+      path = input["path"].to_s.strip
+      content = input["content"].to_s
+      [path, content]
+    end
+
+    def resolve_path(path)
+      if @working_directory
+        File.expand_path(path, @working_directory)
+      else
+        File.expand_path(path)
+      end
+    end
+
+    def validate_target(path)
+      return {error: "Is a directory: #{path}"} if File.directory?(path)
+      {error: "Not writable: #{path}"} if File.exist?(path) && !File.writable?(path)
+    end
+
+    def write_file(path, content)
+      FileUtils.mkdir_p(File.dirname(path))
+      bytes = File.write(path, content)
+      "Wrote #{bytes} bytes to #{path}"
+    rescue Errno::EACCES
+      {error: "Permission denied: #{path}"}
+    rescue Errno::ENOSPC
+      {error: "No space left on device: #{path}"}
+    rescue Errno::EROFS
+      {error: "Read-only file system: #{path}"}
+    end
+  end
+end