ace-support-mac-clipboard 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c558611a5b584d6fcbfb84333bc45ac8cc0673af46f58608dcfa4b004d9d9e44
+  data.tar.gz: f09989c772c93bbbb5a19fae3ce2fcef7a26ab0473f2b3ffa1777bb2e0a3f3f2
+SHA512:
+  metadata.gz: 17c31bd56c10d82e28fe4ec291741e3452f331a6f0b9f0cf7ae3a558f551a13ed898db752200aed1a237ec5ab5fa1d778ce5670dd683167ea07f784f46bb0b57
+  data.tar.gz: 674909b85c99e490026d58b0ec6d8947254d3f1b3a4adc9326e88763b72608976612d513c1cc0b7b659386ea4993b868e5a40940cb71f4c04b87380c876b4b4b

data/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog][1], and this project adheres to [Semantic Versioning][2].
+
+## [Unreleased]
+
+## [0.3.0] - 2026-03-23
+
+### Technical
+- Removed phantom `handbook/**/*` glob from gemspec (no handbook directory exists).
+
+## [0.2.3] - 2026-03-22
+
+### Technical
+- Corrected README integration guidance to reference `ace-idea` clipboard usage instead of `ace-taskflow`.
+
+## [0.2.2] - 2026-03-22
+
+### Technical
+- Refreshed README structure with consistent tagline, overview, basic usage, and ACE project footer
+
+## [0.2.1] - 2026-02-12
+
+### Fixed
+- Guard `require "ace/support/mac_clipboard"` behind platform check to prevent load errors on non-macOS
+- Skip all tests gracefully on non-macOS platforms instead of failing
+
+## [0.2.0] - 2026-01-03
+
+### Changed
+- **BREAKING**: Minimum Ruby version raised to 3.3.0 (was 3.1.0)
+- Standardized gemspec file patterns with deterministic Dir.glob
+- Added MIT LICENSE file
+
+## [0.1.1] - 2025-11-11
+
+### Added
+- Comprehensive test suite with smoke test pattern compatibility
+- Test infrastructure for all core components (Error, ContentType, Reader, ContentParser)
+
+### Fixed
+- Test discovery and execution issues with ace-test integration
+- Module structure and constant loading verification tests
+
+### Changed
+- Update test structure to work with ace-test smoke pattern
+- Improve test coverage for clipboard functionality
+
+## 0.1.0 - 2025-10-13
+
+### Added
+- Initial release of ace-support-mac-clipboard
+- Core clipboard functionality with FFI integration
+- ContentType module for macOS clipboard type mappings
+- Reader class for clipboard content access
+- ContentParser class for data processing
+
+[1]: https://keepachangelog.com/en/1.0.0/
+[2]: https://semver.org/spec/v2.0.0.html

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Czyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,29 @@
+<div align="center">
+  <h1> ACE - Support Mac Clipboard </h1>
+
+  macOS clipboard support for text, files, and image payloads used by ACE tools.
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-support-mac-clipboard"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-support-mac-clipboard.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+**macOS only.** `ace-support-mac-clipboard` integrates with macOS `NSPasteboard` so ACE tools can consume richer clipboard inputs than plain text. It handles screenshots, Finder file selections, and formatted content, presenting normalized Ruby structures to downstream packages.
+
+## Use Cases
+
+**Attach image and context content from clipboard** - support screenshot-based and file-based workflows in ACE tools like [ace-prompt-prep](../ace-prompt-prep) without manual file handling.
+
+**Handle Finder selections and formatted text** - process files and rich content from macOS pasteboard without manual conversion steps.
+
+**Keep platform details isolated** - encapsulate macOS-specific clipboard behavior in one package so the rest of ACE stays platform-neutral.
+
+---
+
+Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+desc "Run tests using ace-test"
+task :test do
+  sh "ace-test"
+end
+
+desc "Run tests directly (CI mode)"
+Minitest::TestTask.create(:ci)
+
+task default: :test

data/lib/ace/support/mac_clipboard/content_parser.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Ace
+  module Support
+    module MacClipboard
+      class ContentParser
+        def self.parse(raw_result)
+          return {text: nil, attachments: []} unless raw_result[:success]
+          return {text: nil, attachments: []} if raw_result[:types].empty?
+
+          pasteboard = raw_result[:raw_pasteboard]
+          types = raw_result[:types]
+
+          text_parts = []
+          attachments = []
+          image_count = 0
+
+          # Classify all types
+          classified = types.map { |uti| [uti, ContentType.classify(uti)] }
+
+          # Process by priority
+          ContentType::PRIORITY_ORDER.each do |category|
+            relevant_utis = classified.select { |_uti, cat| cat == category }.map(&:first)
+
+            case category
+            when :files
+              # Read file URLs once (works for both public.file-url and NSFilenamesPboardType)
+              file_urls = Reader.read_file_urls(pasteboard)
+              file_urls.each do |path|
+                attachments << {
+                  type: :file,
+                  source_path: path,
+                  filename: File.basename(path)
+                }
+              end
+
+            when :image
+              relevant_utis.each do |uti|
+                data = Reader.read_type(pasteboard, uti)
+                next unless data && data.bytesize > 0
+
+                image_count += 1
+                format = ContentType.image_format_from_uti(uti)
+                ext = ContentType::EXTENSIONS[:image][format]
+
+                attachments << {
+                  type: :image,
+                  format: format,
+                  data: data,
+                  filename: "clipboard-image-#{image_count}#{ext}"
+                }
+                break # Only take the first image format
+              end
+
+            when :rtf
+              relevant_utis.each do |uti|
+                data = Reader.read_type(pasteboard, uti)
+                next unless data && data.bytesize > 0
+
+                attachments << {
+                  type: :rtf,
+                  data: data,
+                  filename: "clipboard-content.rtf"
+                }
+                break # Only take the first RTF format
+              end
+
+            when :html
+              relevant_utis.each do |uti|
+                data = Reader.read_type(pasteboard, uti)
+                next unless data && data.bytesize > 0
+
+                attachments << {
+                  type: :html,
+                  data: data,
+                  filename: "clipboard-content.html"
+                }
+                break # Only take the first HTML format
+              end
+
+            when :text
+              relevant_utis.each do |uti|
+                text = Reader.read_string(pasteboard, uti)
+                next unless text && !text.empty?
+
+                text_parts << text
+                break # Only take the first text format
+              end
+            end
+          end
+
+          # Combine all text parts
+          combined_text = text_parts.join("\n\n").strip
+          combined_text = nil if combined_text.empty?
+
+          {
+            text: combined_text,
+            attachments: attachments
+          }
+        end
+
+        def self.parse_text(data)
+          return nil unless data
+
+          data.force_encoding("UTF-8").strip
+        rescue
+          nil
+        end
+
+        def self.parse_file_urls(data)
+          return [] unless data
+
+          # Parse file URL data
+          urls = []
+          url_str = data.force_encoding("UTF-8").strip
+
+          # Handle file:// URLs
+          url_str = url_str.sub(%r{^file://}, "")
+
+          # URL decode
+          url_str = begin
+            URI.decode_www_form_component(url_str)
+          rescue
+            url_str
+          end
+
+          urls << url_str if File.exist?(url_str)
+          urls
+        rescue
+          []
+        end
+
+        def self.parse_image(data, uti)
+          return nil unless data && data.bytesize > 0
+
+          format = ContentType.image_format_from_uti(uti)
+
+          {
+            format: format,
+            data: data
+          }
+        rescue
+          nil
+        end
+
+        def self.parse_rtf(data)
+          return nil unless data && data.bytesize > 0
+
+          data
+        rescue
+          nil
+        end
+
+        def self.parse_html(data)
+          return nil unless data && data.bytesize > 0
+
+          data.force_encoding("UTF-8")
+        rescue
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/mac_clipboard/content_type.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module MacClipboard
+      module ContentType
+        # UTI (Uniform Type Identifier) mappings for macOS clipboard types
+        UTI_TYPES = {
+          # Text types
+          "public.utf8-plain-text" => :text,
+          "public.plain-text" => :text,
+          "NSStringPboardType" => :text,
+
+          # Image types
+          "public.png" => :image,
+          "public.jpeg" => :image,
+          "public.tiff" => :image,
+          "com.apple.icns" => :image,
+
+          # File URLs
+          "public.file-url" => :files,
+          "NSFilenamesPboardType" => :files,
+
+          # Rich text types
+          "public.rtf" => :rtf,
+          "com.apple.rtfd" => :rtf,
+
+          # HTML
+          "public.html" => :html,
+          "NSHTMLPboardType" => :html
+        }.freeze
+
+        # Priority order for processing (higher priority first)
+        PRIORITY_ORDER = [:files, :image, :rtf, :html, :text].freeze
+
+        # File extensions for auto-generated filenames
+        EXTENSIONS = {
+          image: {png: ".png", jpeg: ".jpg", tiff: ".tiff"},
+          rtf: ".rtf",
+          html: ".html"
+        }.freeze
+
+        def self.classify(uti)
+          UTI_TYPES[uti] || :unknown
+        end
+
+        def self.image_format_from_uti(uti)
+          case uti
+          when "public.png" then :png
+          when "public.jpeg" then :jpeg
+          when "public.tiff" then :tiff
+          else :png
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/mac_clipboard/reader.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Ace
+  module Support
+    module MacClipboard
+      class Reader
+        extend FFI::Library
+
+        # Load Objective-C runtime and AppKit framework
+        ffi_lib "/usr/lib/libobjc.dylib"
+        ffi_lib "/System/Library/Frameworks/AppKit.framework/AppKit"
+
+        # Objective-C runtime functions
+        attach_function :objc_getClass, [:string], :pointer
+        attach_function :sel_registerName, [:string], :pointer
+        attach_function :objc_msgSend, [:pointer, :pointer], :pointer
+        attach_function :objc_msgSend_id, :objc_msgSend, [:pointer, :pointer, :pointer], :pointer
+        attach_function :objc_msgSend_uint, :objc_msgSend, [:pointer, :pointer], :uint
+        attach_function :objc_msgSend_uint64, :objc_msgSend, [:pointer, :pointer, :uint64], :pointer
+
+        # Helper to send Objective-C messages
+        def self.objc_send(obj, selector, *args)
+          sel = sel_registerName(selector.to_s)
+          if args.empty?
+            objc_msgSend(obj, sel)
+          else
+            objc_msgSend_id(obj, sel, *args)
+          end
+        end
+
+        # Read clipboard content
+        def self.read
+          return {success: false, error: "Not on macOS"} unless RUBY_PLATFORM.match?(/darwin/)
+
+          pasteboard = get_general_pasteboard
+          return {success: false, error: "Could not access pasteboard"} unless pasteboard
+
+          types = available_types(pasteboard)
+          return {success: true, types: [], text: nil, attachments: []} if types.empty?
+
+          {success: true, types: types, raw_pasteboard: pasteboard}
+        rescue => e
+          {success: false, error: e.message}
+        end
+
+        # Get the general (system) pasteboard
+        def self.get_general_pasteboard
+          ns_pasteboard_class = objc_getClass("NSPasteboard")
+          objc_send(ns_pasteboard_class, "generalPasteboard")
+        end
+
+        # Get all available UTI types on the pasteboard
+        def self.available_types(pasteboard)
+          types_array = objc_send(pasteboard, "types")
+          return [] unless types_array && !types_array.null?
+
+          count = objc_msgSend_uint(types_array, sel_registerName("count"))
+          return [] if count.zero?
+
+          types = []
+          count.times do |i|
+            type_obj = objc_msgSend_uint64(types_array, sel_registerName("objectAtIndex:"), i)
+            next unless type_obj && !type_obj.null?
+
+            utf8_selector = sel_registerName("UTF8String")
+            type_cstr = objc_msgSend(type_obj, utf8_selector)
+            next if type_cstr.null?
+
+            types << type_cstr.read_string
+          end
+
+          types
+        rescue => e
+          warn "Error in available_types: #{e.message}"
+          warn e.backtrace.first(5)
+          []
+        end
+
+        # Read data for a specific UTI type
+        def self.read_type(pasteboard, uti)
+          # Create NSString for the UTI
+          objc_getClass("NSString")
+          uti_str = create_nsstring(uti)
+          return nil unless uti_str
+
+          # Get data from pasteboard
+          data = objc_msgSend_id(pasteboard, sel_registerName("dataForType:"), uti_str)
+          return nil unless data && !data.null?
+
+          # Get byte length
+          length = objc_msgSend_uint(data, sel_registerName("length"))
+          return nil if length.zero?
+
+          # Get bytes pointer
+          bytes = objc_msgSend(data, sel_registerName("bytes"))
+          return nil if bytes.null?
+
+          # Read binary data
+          bytes.read_bytes(length)
+        rescue
+          nil
+        end
+
+        # Read string content for text types
+        def self.read_string(pasteboard, uti)
+          # Try to get as string first
+          objc_getClass("NSString")
+          uti_str = create_nsstring(uti)
+          return nil unless uti_str
+
+          string_obj = objc_msgSend_id(pasteboard, sel_registerName("stringForType:"), uti_str)
+          if string_obj && !string_obj.null?
+            utf8_selector = sel_registerName("UTF8String")
+            cstr = objc_msgSend(string_obj, utf8_selector)
+            return cstr.read_string unless cstr.null?
+          end
+
+          # Fallback to reading as data
+          data = read_type(pasteboard, uti)
+          data&.force_encoding("UTF-8")
+        rescue
+          nil
+        end
+
+        # Read file URLs from pasteboard
+        def self.read_file_urls(pasteboard)
+          # Try NSFilenamesPboardType first (Finder uses this for copied files)
+          file_paths = read_filenames_pboard_type(pasteboard)
+          return file_paths if file_paths.any?
+
+          # Fallback to public.file-url
+          file_paths = read_public_file_url(pasteboard)
+          return file_paths if file_paths.any?
+
+          []
+        rescue => e
+          warn "Error reading file URLs: #{e.message}"
+          []
+        end
+
+        # Read file paths from NSFilenamesPboardType (used by Finder)
+        def self.read_filenames_pboard_type(pasteboard)
+          uti_str = create_nsstring("NSFilenamesPboardType")
+          return [] unless uti_str
+
+          # Get property list (NSArray of file path strings)
+          prop_list_sel = sel_registerName("propertyListForType:")
+          array_obj = objc_msgSend_id(pasteboard, prop_list_sel, uti_str)
+          return [] unless array_obj && !array_obj.null?
+
+          # Get count of files
+          count_sel = sel_registerName("count")
+          count = objc_msgSend_uint(array_obj, count_sel)
+          return [] if count.zero?
+
+          # Extract file paths
+          file_paths = []
+          count.times do |i|
+            obj_at_index_sel = sel_registerName("objectAtIndex:")
+            path_obj = objc_msgSend_uint64(array_obj, obj_at_index_sel, i)
+            next unless path_obj && !path_obj.null?
+
+            utf8_sel = sel_registerName("UTF8String")
+            cstr = objc_msgSend(path_obj, utf8_sel)
+            next if cstr.null?
+
+            path = cstr.read_string
+            file_paths << path if File.exist?(path)
+          end
+
+          file_paths
+        rescue => e
+          warn "Error reading NSFilenamesPboardType: #{e.message}"
+          []
+        end
+
+        # Read file URL from public.file-url
+        def self.read_public_file_url(pasteboard)
+          data = read_type(pasteboard, "public.file-url")
+          return [] unless data
+
+          # Parse URL from data
+          url_str = data.force_encoding("UTF-8").strip
+
+          # Remove "file://" prefix if present
+          url_str = url_str.sub(%r{^file://}, "")
+
+          # URL decode
+          url_str = begin
+            URI.decode_www_form_component(url_str)
+          rescue
+            url_str
+          end
+
+          File.exist?(url_str) ? [url_str] : []
+        rescue
+          []
+        end
+
+        # Helper to create NSString from Ruby string
+        def self.create_nsstring(str)
+          ns_string_class = objc_getClass("NSString")
+          return nil unless ns_string_class
+
+          utf8_selector = sel_registerName("stringWithUTF8String:")
+          objc_msgSend_id(ns_string_class, utf8_selector, FFI::MemoryPointer.from_string(str))
+        rescue
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/mac_clipboard/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module MacClipboard
+      VERSION = "0.3.0"
+    end
+  end
+end

data/lib/ace/support/mac_clipboard.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "mac_clipboard/version"
+require_relative "mac_clipboard/content_type"
+require_relative "mac_clipboard/reader"
+require_relative "mac_clipboard/content_parser"
+
+module Ace
+  module Support
+    module MacClipboard
+      class Error < StandardError; end
+    end
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: ace-support-mac-clipboard
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Michal Czyz
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+description: Provides FFI-based access to macOS NSPasteboard for reading rich clipboard
+  content (images, files, RTF, HTML)
+email:
+- mc@cs3b.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/ace/support/mac_clipboard.rb
+- lib/ace/support/mac_clipboard/content_parser.rb
+- lib/ace/support/mac_clipboard/content_type.rb
+- lib/ace/support/mac_clipboard/reader.rb
+- lib/ace/support/mac_clipboard/version.rb
+homepage: https://github.com/cs3b/ace
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/cs3b/ace
+  source_code_uri: https://github.com/cs3b/ace/tree/main/ace-support-mac-clipboard/
+  changelog_uri: https://github.com/cs3b/ace/blob/main/ace-support-mac-clipboard/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: macOS NSPasteboard integration for ACE
+test_files: []