abbu 0.2.0 → 0.8.1

data/lib/abbu/contact.rb

@@ -4,19 +4,22 @@
 module Abbu
   class Contact
     attr_accessor :first_name, :middle_name, :last_name, :emails,
-                  :phones, :company, :addresses, :groups, :nickname,
+                  :phones, :company, :addresses, :groups, :group_memberships, :nickname,
                   :prefix, :suffix, :job_title, :department, :maiden_name,
                   :phonetic_first_name, :phonetic_middle_name, :phonetic_last_name,
                   :phonetic_company, :pronouns, :ringtone, :texttone,
                   :urls, :notes, :related_names, :social_profiles,
                   :birthday, :anniversary, :dates, :instant_messages,
-                  :verification_code, :lunar_birthday
+                  :verification_code, :lunar_birthday,
+                  :image_uri, :image_path,
+                  :created_at, :modified_at, :source
 
-    def initialize
+    def initialize # rubocop:disable Metrics/MethodLength
       @emails = []
       @phones = []
       @addresses = []
       @groups = []
+      @group_memberships = []
       @urls = []
       @notes = []
       @related_names = []

data/lib/abbu/diagnostic.rb

@@ -0,0 +1,27 @@
+# lib/abbu/diagnostic.rb
+# frozen_string_literal: true
+
+module Abbu
+  class Diagnostic
+    attr_reader :category, :context, :message, :parser, :source
+
+    def initialize(category:, message:, parser:, source:, context: {})
+      @category = category.to_sym
+      @context = context.freeze
+      @message = message.to_s.freeze
+      @parser = parser.to_sym
+      @source = source.to_s.freeze
+      freeze
+    end
+
+    def to_h
+      {
+        category: category,
+        message: message,
+        parser: parser,
+        source: source,
+        context: context
+      }
+    end
+  end
+end

data/lib/abbu/exporters/csv_exporter.rb

@@ -28,7 +28,7 @@ module Abbu
 
       def headers
         %w[Name First Middle Last Email Phone Company Address Groups URLs Notes RelatedNames SocialProfiles Birthday
-           Anniversary InstantMessages VerificationCode LunarBirthday]
+           Anniversary InstantMessages VerificationCode LunarBirthday ImagePath]
       end
 
       def row(contact)
@@ -50,7 +50,7 @@ module Abbu
           format_related_names(contact.related_names), format_social_profiles(contact.social_profiles),
           format_date(contact.birthday), format_date(contact.anniversary),
           format_instant_messages(contact.instant_messages), contact.verification_code,
-          format_date(contact.lunar_birthday)
+          format_date(contact.lunar_birthday), contact.image_path.to_s
         ]
       end
 

data/lib/abbu/exporters/json_exporter.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'time'
 
 module Abbu
   module Exporters
@@ -52,7 +53,12 @@ module Abbu
           dates: contact.dates,
           instant_messages: contact.instant_messages,
           verification_code: contact.verification_code,
-          lunar_birthday: contact.lunar_birthday
+          lunar_birthday: contact.lunar_birthday,
+          image_uri: contact.image_uri,
+          image_path: contact.image_path&.to_s,
+          created_at: contact.created_at&.iso8601,
+          modified_at: contact.modified_at&.iso8601,
+          source: contact.source
         }.compact
       end
     end

data/lib/abbu/exporters/vcard_document.rb

@@ -0,0 +1,54 @@
+# lib/abbu/exporters/vcard_document.rb
+# frozen_string_literal: true
+
+require_relative 'vcard_encoding'
+
+module Abbu
+  module Exporters
+    # Per-card grouping avoids ambiguous associations between repeated labels.
+    class VcardDocument
+      TYPES = {
+        'EMAIL' => %w[INTERNET X400 PREF],
+        'TEL' => %w[HOME WORK PREF VOICE FAX MSG CELL PAGER BBS MODEM CAR ISDN VIDEO PCS],
+        'ADR' => %w[DOM INTL POSTAL PARCEL HOME WORK PREF],
+        'IMPP' => %w[PERSONAL BUSINESS HOME WORK MOBILE PREF]
+      }.transform_values(&:freeze).freeze
+
+      def initialize
+        @lines = ['BEGIN:VCARD', 'VERSION:3.0']
+        @group_number = 0
+      end
+
+      def <<(line)
+        @lines << line
+      end
+
+      def labeled(property, value, entry, default_type: nil)
+        type = standard_type(property, entry[:label]) || default_type
+        header = type ? "#{property};TYPE=#{type}" : property
+        label = entry[:raw_label] || entry[:label]
+        return self << "#{header}:#{value}" if label.nil?
+
+        @group_number += 1
+        self << "item#{@group_number}.#{header}:#{value}"
+        self << "item#{@group_number}.X-ABLABEL:#{VcardEncoding.text(label)}"
+      end
+
+      def to_s
+        lines = (@lines + ['END:VCARD']).map { |line| VcardEncoding.fold(line) }
+        "#{lines.join("\r\n")}\r\n"
+      end
+
+      private
+
+      def standard_type(property, label)
+        return unless label.to_s.match?(/\A[A-Za-z0-9-]+\z/)
+
+        type = label.upcase
+        return 'INTERNET,PREF' if property == 'EMAIL' && type == 'PREF'
+
+        type if TYPES.fetch(property, []).include?(type)
+      end
+    end
+  end
+end

data/lib/abbu/exporters/vcard_encoding.rb

@@ -0,0 +1,54 @@
+# lib/abbu/exporters/vcard_encoding.rb
+# frozen_string_literal: true
+
+require 'uri'
+
+module Abbu
+  module Exporters
+    # Internal wire encoding; URI values and TEXT values have different grammars.
+    module VcardEncoding
+      module_function
+
+      def text(value)
+        utf8(value).gsub(/\\|;|,|\r\n|\r|\n/) do |character|
+          character.match?(/[\r\n]/) ? '\\n' : "\\#{character}"
+        end
+      end
+
+      def structured(values)
+        values.map { |value| text(value) }.join(';')
+      end
+
+      def uri(value)
+        URI::DEFAULT_PARSER.escape(utf8(value), %r{[^A-Za-z0-9\-._~:/?#\[\]@!$&'()*+,;=%]})
+      end
+
+      def token(value)
+        string = utf8(value)
+        raise ArgumentError, 'vCard parameter must be an ASCII token' unless string.match?(/\A[A-Za-z0-9-]+\z/)
+
+        string
+      end
+
+      def fold(line)
+        parts = [+'']
+        utf8(line).each_char do |character|
+          parts << +' ' if parts.last.bytesize + character.bytesize > 75
+          parts.last << character
+        end
+        parts.join("\r\n")
+      end
+
+      def utf8(value)
+        string = value.to_s.encode(Encoding::UTF_8)
+        raise ArgumentError, 'vCard text has invalid encoding' unless string.valid_encoding?
+        if string.match?(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/)
+          raise ArgumentError,
+                'vCard text contains an unsupported control character'
+        end
+
+        string
+      end
+    end
+  end
+end

data/lib/abbu/exporters/vcard_exporter.rb

@@ -1,6 +1,10 @@
 # lib/abbu/exporters/vcard_exporter.rb
 # frozen_string_literal: true
 
+require 'uri'
+
+require_relative 'vcard_document'
+
 module Abbu
   module Exporters
     class VcardExporter
@@ -9,21 +13,21 @@ module Abbu
       end
 
       def to_file(path)
-        File.write(path, generate)
+        File.binwrite(path, generate)
       end
 
       def to_stdout
-        puts generate
+        print generate
       end
 
       private
 
       def generate
-        @contacts.map { |c| vcard_for(c) }.join("\n")
+        @contacts.map { |c| vcard_for(c) }.join
       end
 
       def vcard_for(contact) # rubocop:disable Metrics/MethodLength
-        lines = ['BEGIN:VCARD', 'VERSION:3.0']
+        lines = VcardDocument.new
 
         append_name_fields(lines, contact)
         append_emails(lines, contact)
@@ -35,14 +39,14 @@ module Abbu
         append_instant_messages(lines, contact)
         append_verification_code(lines, contact)
         append_notes(lines, contact)
+        append_photo(lines, contact)
 
-        lines << 'END:VCARD'
-        lines.join("\n")
+        lines.to_s
       end
 
       def append_name_fields(lines, contact)
-        lines << "FN:#{contact.full_name}"
-        lines << "N:#{name_components(contact).join(';')}"
+        lines << "FN:#{VcardEncoding.text(contact.full_name)}"
+        lines << "N:#{VcardEncoding.structured(name_components(contact))}"
         append_nickname(lines, contact)
         append_company(lines, contact)
         append_title(lines, contact)
@@ -54,68 +58,81 @@ module Abbu
       end
 
       def append_nickname(lines, contact)
-        lines << "NICKNAME:#{contact.nickname}" if contact.nickname
+        lines << "NICKNAME:#{VcardEncoding.text(contact.nickname)}" if contact.nickname
       end
 
       def append_company(lines, contact)
-        lines << "ORG:#{contact.company}" if contact.company
+        lines << "ORG:#{VcardEncoding.text(contact.company)}" if contact.company
       end
 
       def append_title(lines, contact)
-        lines << "TITLE:#{contact.job_title}" if contact.job_title
+        lines << "TITLE:#{VcardEncoding.text(contact.job_title)}" if contact.job_title
       end
 
       def append_phonetic_names(lines, contact)
-        lines << "X-PHONETIC-FIRST-NAME:#{contact.phonetic_first_name}" if contact.phonetic_first_name
-        lines << "X-PHONETIC-MIDDLE-NAME:#{contact.phonetic_middle_name}" if contact.phonetic_middle_name
-        lines << "X-PHONETIC-LAST-NAME:#{contact.phonetic_last_name}" if contact.phonetic_last_name
+        %i[first middle last].each do |part|
+          value = contact.public_send(:"phonetic_#{part}_name")
+          lines << "X-PHONETIC-#{part.upcase}-NAME:#{VcardEncoding.text(value)}" if value
+        end
       end
 
       def append_verification_code(lines, contact)
-        lines << "X-VERIFICATION-CODE:#{contact.verification_code}" if contact.verification_code
+        lines << "X-VERIFICATION-CODE:#{VcardEncoding.text(contact.verification_code)}" if contact.verification_code
+      end
+
+      def append_photo(lines, contact)
+        return unless contact.image_path
+
+        lines << "PHOTO;VALUE=URI:#{file_uri(contact.image_path)}"
+      end
+
+      def file_uri(path)
+        escaped_path = URI::DEFAULT_PARSER.escape(path.to_s)
+        URI::Generic.build(scheme: 'file', path: escaped_path)
       end
 
       def append_notes(lines, contact)
-        contact.notes.each { |n| lines << "NOTE:#{n}" }
+        contact.notes.each { |n| lines << "NOTE:#{VcardEncoding.text(n)}" }
       end
 
       def append_emails(lines, contact)
         contact.emails.each do |e|
-          label = e[:label] || 'INTERNET'
-          lines << "EMAIL;TYPE=#{label}:#{e[:address]}"
+          lines.labeled('EMAIL', VcardEncoding.text(e[:address]), e, default_type: 'INTERNET')
         end
       end
 
       def append_phones(lines, contact)
         contact.phones.each do |p|
-          label = p[:label] || 'VOICE'
-          lines << "TEL;TYPE=#{label}:#{p[:number]}"
+          lines.labeled('TEL', VcardEncoding.text(p[:number]), p, default_type: 'VOICE')
         end
       end
 
       def append_addresses(lines, contact)
         contact.addresses.each do |a|
-          label = a[:label] || 'HOME'
-          lines << "ADR;TYPE=#{label}:;;#{a[:street]};#{a[:city]};#{a[:state]};#{a[:zip]};#{a[:country]}"
+          value = VcardEncoding.structured([nil, nil, a[:street], a[:city], a[:state], a[:zip], a[:country]])
+          lines.labeled('ADR', value, a)
         end
       end
 
       def append_urls(lines, contact)
         contact.urls.each do |u|
-          lines << "URL:#{u[:url]}"
+          lines.labeled('URL', VcardEncoding.uri(u[:url]), u)
         end
       end
 
       def append_social_profiles(lines, contact)
         contact.social_profiles.each do |sp|
-          lines << "X-SOCIALPROFILE;TYPE=#{sp[:service]}:#{sp[:username]}"
+          type = sp[:service] ? ";TYPE=#{VcardEncoding.token(sp[:service])}" : ''
+          lines << "X-SOCIALPROFILE#{type}:#{VcardEncoding.text(sp[:username])}"
         end
       end
 
       def append_instant_messages(lines, contact)
         contact.instant_messages.each do |im|
           service = im[:service]&.downcase || 'unknown'
-          lines << "IMPP;TYPE=#{im[:label]}:#{service}:#{im[:address]}"
+          raise ArgumentError, 'IM service must be a URI scheme' unless service.match?(/\A[a-z][a-z0-9+.-]*\z/)
+
+          lines.labeled('IMPP', "#{service}:#{VcardEncoding.uri(im[:address])}", im)
         end
       end
 
@@ -124,8 +141,8 @@ module Abbu
         lines << "X-LUNAR-BDAY:#{format_vcard_date(contact.lunar_birthday)}" if contact.lunar_birthday
         return unless contact.anniversary
 
-        lines << "X-ABDATE;type=pref:#{format_vcard_date(contact.anniversary)}"
-        lines << 'X-ABLABEL:_$!<Anniversary>!$_'
+        entry = { label: 'Anniversary' }.merge(contact.anniversary.compact)
+        lines.labeled('X-ABDATE', format_vcard_date(contact.anniversary), entry)
       end
 
       def format_vcard_date(date)

data/lib/abbu/group.rb

@@ -0,0 +1,28 @@
+# lib/abbu/group.rb
+# frozen_string_literal: true
+
+require_relative 'query'
+
+module Abbu
+  # A snapshot of an observed SQLite group membership, local to one input file.
+  # Names and record keys are evidence, not globally unique Apple identifiers.
+  class Group
+    attr_reader :record_id, :name, :source, :contacts
+
+    def initialize(record_id:, name:, source:, contacts:)
+      @record_id = record_id
+      @name = name&.dup&.freeze
+      @source = source.transform_values { |value| value&.dup&.freeze }.freeze
+      @contacts = Query.new(contacts.to_a.uniq).freeze
+      freeze
+    end
+
+    def include?(contact)
+      contacts.any? { |member| member.equal?(contact) }
+    end
+
+    def to_h
+      { record_id: record_id, name: name, source: source, contact_count: contacts.count }
+    end
+  end
+end

data/lib/abbu/group_catalog.rb

@@ -0,0 +1,32 @@
+# lib/abbu/group_catalog.rb
+# frozen_string_literal: true
+
+require_relative 'group'
+
+module Abbu
+  class GroupCatalog
+    def initialize(contacts)
+      @contacts = contacts
+    end
+
+    def groups
+      entries_by_key = memberships.group_by { |contact, membership| [contact.source[:path], membership[:record_id]] }
+      groups = entries_by_key.values.map { |entries| build_group(entries) }
+      groups.sort_by { |group| [group.source[:relative_path], group.record_id] }.freeze
+    end
+
+    private
+
+    def memberships
+      @contacts.flat_map do |contact|
+        contact.group_memberships.map { |membership| [contact, membership] }
+      end
+    end
+
+    def build_group(entries)
+      contact, membership = entries.first
+      Group.new(record_id: membership[:record_id], name: membership[:name], source: contact.source,
+                contacts: entries.map(&:first))
+    end
+  end
+end

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,117 @@
+# lib/abbu/live_store.rb
+# frozen_string_literal: true
+
+require 'pathname'
+require 'sqlite3'
+require_relative 'parsers/sqlite_parser'
+require_relative 'source_catalog'
+
+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
+
+    def sources
+      @sources ||= SourceCatalog.new(database_paths, root_path: @path, contacts: contacts).sources
+    end
+
+    def groups
+      @groups ||= sources.flat_map(&:groups).freeze
+    end
+
+    def groups_for(contact)
+      groups.select { |group| group.include?(contact) }
+    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