abbu 0.1.2 → 0.4.0

data/lib/abbu/image_extractor.rb

@@ -0,0 +1,134 @@
+# lib/abbu/image_extractor.rb
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'pathname'
+
+module Abbu
+  class ImageExtractor
+    Result = Struct.new(:files, :diagnostics, keyword_init: true)
+
+    SIGNATURES = {
+      jpeg: { extension: 'jpg', media_type: 'image/jpeg' },
+      png: { extension: 'png', media_type: 'image/png' },
+      gif: { extension: 'gif', media_type: 'image/gif' },
+      heic: { extension: 'heic', media_type: 'image/heic' }
+    }.freeze
+
+    def initialize(contacts)
+      @contacts = contacts
+    end
+
+    def extract(output_dir)
+      destination = Pathname.new(output_dir).expand_path
+      FileUtils.mkdir_p(destination)
+      destination = destination.realpath
+      files = []
+      diagnostics = []
+      used_names = Hash.new(0)
+
+      @contacts.each do |contact|
+        extract_contact(contact, destination, files, diagnostics, used_names)
+      end
+
+      Result.new(files: files.freeze, diagnostics: diagnostics.freeze).freeze
+    end
+
+    private
+
+    def extract_contact(contact, destination, files, diagnostics, used_names)
+      return unless contact.image_uri
+
+      source = contact.image_path
+      return add_diagnostic(diagnostics, :missing_image, contact, source) unless source&.file?
+
+      type = detect_type(source)
+      return add_diagnostic(diagnostics, :unsupported_image, contact, source) unless type
+
+      target = destination.join(unique_filename(contact, source, type[:extension], used_names))
+      return add_diagnostic(diagnostics, :destination_exists, contact, source) unless copy_image(source, target)
+
+      files << file_record(contact, source, target, type)
+    rescue IOError, SystemCallError => e
+      add_diagnostic(diagnostics, :unreadable_image, contact, source, e.message)
+    end
+
+    def copy_image(source, target)
+      File.open(target, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |output|
+        source.open('rb') { |input| IO.copy_stream(input, output) }
+      end
+      true
+    rescue Errno::EEXIST
+      false
+    end
+
+    def detect_type(path)
+      header = path.open('rb') { |file| file.read(32) }.to_s.b
+      SIGNATURES[kind_for(header)]
+    end
+
+    def kind_for(header)
+      return :jpeg if header.start_with?("\xFF\xD8\xFF".b)
+      return :png if header.start_with?("\x89PNG\r\n\x1A\n".b)
+      return :gif if header.start_with?('GIF87a', 'GIF89a')
+
+      :heic if heic?(header)
+    end
+
+    def heic?(header)
+      header.byteslice(4, 4) == 'ftyp' && %w[heic heix hevc hevx mif1 msf1].include?(header.byteslice(8, 4))
+    end
+
+    def unique_filename(contact, source, extension, used_names)
+      readable = sanitize(contact.full_name)
+      readable = 'contact' if readable.empty?
+      identifier = sanitize(contact.image_uri.to_s)
+      identifier = 'image' if identifier.empty?
+      fingerprint = Digest::SHA256.hexdigest(provenance_key(contact, source))[0, 10]
+      base = [readable, identifier, fingerprint].join('--')
+      used_names[base] += 1
+      suffix = used_names[base] == 1 ? '' : "-#{used_names[base]}"
+      "#{base}#{suffix}.#{extension}"
+    end
+
+    def sanitize(value)
+      value.unicode_normalize(:nfc)
+           .gsub(%r{[\\/:*?"<>|\p{Cntrl}]+}u, '-')
+           .gsub(/[^\p{Alnum}\p{Mark}_ -]+/u, '-')
+           .strip
+           .gsub(/[ .-]+\z/, '')
+           .gsub(/\s+/, '-')
+           .squeeze('-')
+           .then { |name| name[0, 80] }
+    end
+
+    def provenance_key(contact, source)
+      [contact.source&.fetch(:relative_path, nil), source.expand_path, contact.full_name, contact.image_uri].join("\0")
+    end
+
+    def file_record(contact, source, target, type)
+      {
+        contact: contact,
+        image_uri: contact.image_uri,
+        source_path: source.expand_path,
+        path: target,
+        media_type: type[:media_type]
+      }.freeze
+    end
+
+    def diagnostic(code, contact, source, detail = nil)
+      {
+        code: code,
+        contact_name: contact.full_name,
+        image_uri: contact.image_uri,
+        source_path: source&.expand_path,
+        detail: detail
+      }.compact.freeze
+    end
+
+    def add_diagnostic(diagnostics, code, contact, source, detail = nil)
+      diagnostics << diagnostic(code, contact, source, detail)
+    end
+  end
+end

data/lib/abbu/live_store.rb

@@ -0,0 +1,104 @@
+# lib/abbu/live_store.rb
+# frozen_string_literal: true
+
+require 'pathname'
+require 'sqlite3'
+require_relative 'parsers/sqlite_parser'
+
+module Abbu
+  class LiveStore
+    DATABASE_GLOB = 'AddressBook-v*.abcddb'
+    DEFAULT_RELATIVE_PATH = 'Library/Application Support/AddressBook'
+
+    class Error < StandardError; end
+    class NotFoundError < Error; end
+    class PermissionError < Error; end
+    class UnsupportedPlatformError < Error; end
+
+    attr_reader :diagnostics, :path
+
+    def self.default_path(home: Dir.home, platform: RUBY_PLATFORM)
+      unless platform.include?('darwin')
+        raise UnsupportedPlatformError,
+              'Automatic live Contacts discovery is available only on macOS; supply an AddressBook directory path.'
+      end
+
+      Pathname.new(home).join(DEFAULT_RELATIVE_PATH)
+    end
+
+    def initialize(path = nil, strict: false)
+      @strict = strict
+      @diagnostics = []
+      @path = Pathname.new(path || self.class.default_path).expand_path
+      validate!
+    end
+
+    def contacts
+      @contacts ||= Parsers::SqliteParser.new(
+        database_paths, root_path: @path, readonly: true, diagnostics: diagnostics, strict: @strict
+      ).contacts
+    rescue SQLite3::CantOpenException, Errno::EACCES => e
+      raise permission_error(e.message)
+    end
+
+    def database_paths
+      @database_paths ||= discover_database_paths.tap do |paths|
+        raise NotFoundError, missing_database_message if paths.empty?
+      end
+    end
+
+    private
+
+    def validate!
+      stat = @path.stat
+      raise NotFoundError, "Live Contacts store is not a directory: #{@path}" unless stat.directory?
+
+      ensure_readable_directory!(@path)
+    rescue Errno::ENOENT
+      raise NotFoundError, "Live Contacts store not found: #{@path}"
+    rescue Errno::EACCES => e
+      raise permission_error(e.message)
+    end
+
+    def discover_database_paths
+      paths = @path.glob(DATABASE_GLOB)
+      sources_path = @path.join('Sources')
+      paths.concat(source_database_paths(sources_path)) if sources_path.exist?
+      paths.sort.each { |db_path| ensure_readable_file!(db_path) }
+    rescue Errno::EACCES => e
+      raise permission_error(e.message)
+    end
+
+    def source_database_paths(sources_path)
+      ensure_readable_directory!(sources_path)
+      sources_path.children.sort.select(&:directory?).flat_map do |source_path|
+        ensure_readable_directory!(source_path)
+        source_path.glob(DATABASE_GLOB)
+      end
+    end
+
+    def ensure_readable_directory!(path)
+      return if path.readable? && path.executable?
+
+      raise permission_error("directory is not readable: #{path}")
+    end
+
+    def ensure_readable_file!(path)
+      return if path.file? && path.readable?
+
+      raise permission_error("database is not readable: #{path}")
+    end
+
+    def missing_database_message
+      "No #{DATABASE_GLOB} databases found in live Contacts store: #{@path}"
+    end
+
+    def permission_error(detail)
+      PermissionError.new(
+        "Cannot read live Contacts store at #{@path} (#{detail}). " \
+        'Grant Full Disk Access to the terminal or application running abbu in ' \
+        'System Settings > Privacy & Security > Full Disk Access, then retry.'
+      )
+    end
+  end
+end

data/lib/abbu/parse_error.rb

@@ -0,0 +1,13 @@
+# lib/abbu/parse_error.rb
+# frozen_string_literal: true
+
+module Abbu
+  class ParseError < StandardError
+    attr_reader :diagnostic
+
+    def initialize(diagnostic)
+      @diagnostic = diagnostic
+      super("#{diagnostic.message} (#{diagnostic.source})")
+    end
+  end
+end

data/lib/abbu/parsers/plist_parser.rb

@@ -1,16 +1,184 @@
 # lib/abbu/parsers/plist_parser.rb
 # frozen_string_literal: true
 
+require 'plist'
+require_relative '../contact'
+require_relative '../diagnostic'
+require_relative '../parse_error'
+require_relative '../utils/label_normalizer'
+require_relative '../utils/source_descriptor'
+
 module Abbu
   module Parsers
     class PlistParser
-      def initialize(path)
-        @path = path
+      # Maps plist keys → Contact attr_accessor names for simple string fields
+      FIELD_MAP = {
+        'First' => :first_name, 'Middle' => :middle_name,
+        'Last' => :last_name,
+        'Nickname' => :nickname,  'Title' => :prefix,
+        'Suffix' => :suffix,      'Organization' => :company,
+        'JobTitle' => :job_title, 'Department' => :department,
+        'MaidenName' => :maiden_name, 'VerificationCode' => :verification_code,
+        'PhoneticFirst' => :phonetic_first_name,
+        'PhoneticMiddle' => :phonetic_middle_name,
+        'PhoneticLast' => :phonetic_last_name
+      }.freeze
+
+      # Accepts either a directory path (scans for *.abcdp) or an array of file paths
+      attr_reader :diagnostics
+
+      def initialize(paths, root_path: nil, diagnostics: nil, strict: false)
+        @paths = resolve_paths(paths)
+        @root_path = root_path
+        @diagnostics = diagnostics || []
+        @strict = strict
       end
 
       def contacts
-        warn 'Plist parsing not yet implemented — no .abcddb found in this archive.'
-        []
+        @paths.filter_map { |file| parse_file(file) }
+      end
+
+      private
+
+      def resolve_paths(paths)
+        case paths
+        when Array
+          paths.map { |p| Pathname.new(p) }
+        else
+          path = Pathname.new(paths)
+          return [] unless path.exist?
+
+          path.directory? ? path.glob('*.abcdp').sort : [path]
+        end
+      end
+
+      def parse_file(file)
+        data = Plist.parse_xml(file.to_s)
+        return recover(file) unless data.is_a?(Hash)
+
+        build_contact(data, file)
+      rescue ParseError
+        raise
+      rescue ArgumentError, EOFError, Plist::UnimplementedElementError, SystemCallError, TypeError
+        recover(file)
+      end
+
+      def recover(file)
+        diagnostic = Diagnostic.new(
+          category: :malformed_record,
+          message: 'Unable to parse plist contact record',
+          parser: :plist,
+          source: file,
+          context: {}
+        )
+        diagnostics << diagnostic
+        raise ParseError, diagnostic if @strict
+      end
+
+      def build_contact(data, file)
+        contact = Contact.new
+        assign_flat_fields(contact, data)
+        assign_multi_value_fields(contact, data)
+        contact.source = Utils::SourceDescriptor.new(file, root_path: @root_path).to_h
+        contact
+      end
+
+      def assign_flat_fields(contact, data)
+        FIELD_MAP.each do |plist_key, attr|
+          contact.public_send(:"#{attr}=", data[plist_key])
+        end
+      end
+
+      def assign_multi_value_fields(contact, data) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        contact.emails          = extract_labeled_values(data, 'Email', :address)
+        contact.phones          = extract_labeled_values(data, 'Phone', :number)
+        contact.addresses       = extract_addresses(data)
+        contact.urls            = extract_labeled_values(data, 'URLs', :url)
+        contact.notes           = extract_notes(data)
+        contact.related_names   = extract_labeled_values(data, 'RelatedNames', :name)
+        contact.social_profiles = extract_social_profiles(data)
+        contact.instant_messages = extract_instant_messages(data)
+
+        contact.birthday = extract_birthday(data)
+        contact.lunar_birthday = extract_lunar_birthday(data)
+        contact.dates = extract_dates(data)
+        contact.anniversary = contact.dates.find { |d| d[:label] == 'Anniversary' }
+      end
+
+      def extract_labeled_values(data, key, value_key)
+        return [] unless data[key]&.dig('values')
+
+        data[key]['values'].map do |entry|
+          { value_key => entry['value'], **label_fields(entry['label']) }
+        end
+      end
+
+      def extract_addresses(data) # rubocop:disable Metrics/MethodLength
+        return [] unless data['Address']&.dig('values')
+
+        data['Address']['values'].map do |entry|
+          addr = entry['value'] || {}
+          {
+            street: addr['Street'],
+            city: addr['City'],
+            state: addr['State'],
+            zip: addr['ZIP'],
+            country: addr['Country'],
+            **label_fields(entry['label'])
+          }
+        end
+      end
+
+      def extract_notes(data)
+        note = data['Note']
+        note ? [note] : []
+      end
+
+      def extract_social_profiles(data)
+        return [] unless data['SocialProfile']&.dig('values')
+
+        data['SocialProfile']['values'].map do |entry|
+          profile = entry['value'] || {}
+          { service: profile['serviceName'], username: profile['username'] }
+        end
+      end
+
+      def extract_instant_messages(data)
+        return [] unless data['InstantMessage']&.dig('values')
+
+        data['InstantMessage']['values'].map do |entry|
+          msg = entry['value'] || {}
+          { address: msg['address'], service: msg['serviceName'], **label_fields(entry['label']) }
+        end
+      end
+
+      def extract_birthday(data)
+        val = data['Birthday']
+        return nil unless val.respond_to?(:year)
+
+        { year: val.year, month: val.month, day: val.day, label: 'Birthday', raw_label: nil }
+      end
+
+      def extract_lunar_birthday(data)
+        val = data['LunarBirthday']
+        return nil unless val.respond_to?(:year)
+
+        { year: val.year, month: val.month, day: val.day, label: 'LunarBirthday', raw_label: nil }
+      end
+
+      def extract_dates(data)
+        return [] unless data['Dates']&.dig('values')
+
+        data['Dates']['values'].filter_map do |entry|
+          val = entry['value']
+          next unless val.respond_to?(:year)
+
+          { year: val.year, month: val.month, day: val.day, **label_fields(entry['label']) }
+        end
+      end
+
+      def label_fields(raw_label)
+        { label: Utils::LabelNormalizer.normalize(raw_label), raw_label: raw_label }
       end
     end
   end