abbu 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4e7f9f82489460fb204dd66e345d8ce69e3a81944a9568cb81ae2dc84b41ed0e
+  data.tar.gz: 379defbf4b95f173d6afeaa255787e9f4a051562edf4428626f9048c32c3af66
+SHA512:
+  metadata.gz: 11c08d30dbf68e633f072784e6d9a505bebc1dea90b3d527ec5472425588fe169dacb81b960469af9bd431b74b457ac9ef7ac637cad7357cd2cf25c9c1417f1f
+  data.tar.gz: 1eaf8b0d1b0733f4cb53fcbc6fe5dc11d0725acbb96878ec7677e1830501550bad2a035cf37c2c66c5e2b3da81576a10f0a3498192d0481c46deed5c8a7aacb5

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+<!-- CHANGELOG.md -->
+
+# Changelog
+
+All notable changes to `abbu` are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-12
+
+### Added
+
+- `Abbu.open(path)` entry point returning an `Archive`
+- `Archive#contacts` — reads contacts from SQLite or falls back to plist stub
+- `Archive#sqlite?` — detects modern `.abcddb` bundles
+- `Contact` object with `first_name`, `last_name`, `emails`, `phones`, `company`, `full_name`
+- `Parsers::SqliteParser` — queries `ZABCDRECORD`, `ZABCDEMAILADDRESS`, `ZABCDPHONENUMBER`
+- `Parsers::PlistParser` — stub with warning (legacy `.abcdp` support in v0.2)
+- `Exporters::CsvExporter` — `to_file` and `to_stdout`
+- `Exporters::JsonExporter` — `to_file` and `to_stdout`
+- `Exporters::VcardExporter` — `to_file` and `to_stdout` (vCard 3.0)
+- `Utils::Deduplicator` — groups contacts by first email, returns duplicates hash
+- `bin/abbu` CLI with `--format`, `--output`, `--stats`, `--dedupe`, `--version`
+- Rake tasks: `abbu:export`, `abbu:dedupe`, `abbu:stats`
+- Example scripts: CSV, JSON, vCard, API, CRM sync, stats, dedupe
+- `docs/ABBU.md` — file format reference
+- RSpec test suite with 100% coverage target
+- Guard + RuboCop DX loop
+- GitHub Actions CI (Ruby 3.2 + 3.3)
+
+---
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stan Carver II
+
+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,132 @@
+<!-- README.md -->
+
+# abbu
+
+Read and process Apple Contacts `.abbu` archives in Ruby.
+
+## Features
+
+- Parse ABBU (Apple Contacts export) bundles
+- SQLite-backed contact extraction (modern macOS)
+- Legacy plist format detection (stub, v0.2 roadmap)
+- Export to CSV, JSON, vCard
+- CLI + Ruby API
+- Duplicate detection
+
+## Installation
+
+```bash
+gem install abbu
+```
+
+Or add to your `Gemfile`:
+
+```ruby
+gem "abbu"
+```
+
+## Usage
+
+### Ruby API
+
+```ruby
+require "abbu"
+
+archive = Abbu.open("Contacts.abbu")
+contacts = archive.contacts
+
+contacts.first.full_name   # => "Stan Carver"
+contacts.first.emails      # => ["stan@example.com"]
+contacts.first.phones      # => ["555-1234"]
+```
+
+### Export
+
+```ruby
+# CSV
+Abbu::Exporters::CsvExporter.new(archive.contacts).to_file("contacts.csv")
+
+# JSON
+Abbu::Exporters::JsonExporter.new(archive.contacts).to_file("contacts.json")
+
+# vCard
+Abbu::Exporters::VcardExporter.new(archive.contacts).to_file("contacts.vcf")
+```
+
+### Duplicate Detection
+
+```ruby
+dupes = Abbu::Utils::Deduplicator.new(archive.contacts).duplicates
+dupes.each do |email, contacts|
+  puts "Duplicate: #{email}"
+  contacts.each { |c| puts "  - #{c.full_name}" }
+end
+```
+
+## CLI
+
+```bash
+# Export to CSV
+abbu Contacts.abbu -f csv -o contacts.csv
+
+# JSON to stdout (pipeable)
+abbu Contacts.abbu -f json | jq .
+
+# vCard export
+abbu Contacts.abbu -f vcard -o contacts.vcf
+
+# Stats
+abbu Contacts.abbu --stats
+
+# Find duplicates
+abbu Contacts.abbu --dedupe
+```
+
+## Rake Tasks
+
+```ruby
+# In your Rakefile:
+load "tasks/abbu.rake"
+```
+
+```bash
+rake abbu:export[Contacts.abbu]
+rake abbu:dedupe[Contacts.abbu]
+rake abbu:stats[Contacts.abbu]
+```
+
+## ABBU File Format
+
+See [`docs/ABBU.md`](docs/ABBU.md) for a full explanation of the archive structure,
+SQLite table schema, and format history.
+
+## Roadmap
+
+| Version | Features                                    |
+|---------|---------------------------------------------|
+| v0.1.0  | SQLite parsing, CSV/JSON/vCard export, CLI  |
+| v0.2.0  | Plist parser, image extraction              |
+| v0.3.0  | Fuzzy dedupe (Levenshtein), merge engine    |
+| v1.0.0  | Sync adapters (Printavo, HubSpot, CRM)      |
+
+## Development
+
+```bash
+mise exec -- bundle install
+mise exec -- bundle exec guard    # DX loop: auto-test + auto-lint
+mise exec -- bundle exec rspec    # run specs
+mise exec -- bundle exec rubocop  # lint
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/bin/abbu

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+# bin/abbu
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'optparse'
+require 'abbu'
+
+options = {
+  format: nil,
+  output: nil,
+  dedupe: false,
+  stats: false
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = 'Usage: abbu <file.abbu> [options]'
+
+  opts.on('-f', '--format FORMAT', %w[csv json vcard], 'Export format (csv, json, vcard)') do |f|
+    options[:format] = f
+  end
+
+  opts.on('-o', '--output FILE', 'Output file (default: stdout)') do |o|
+    options[:output] = o
+  end
+
+  opts.on('--stats', 'Print contact statistics') do
+    options[:stats] = true
+  end
+
+  opts.on('--dedupe', 'Find and print duplicate contacts') do
+    options[:dedupe] = true
+  end
+
+  opts.on('-v', '--version', 'Print version') do
+    puts "abbu #{Abbu::VERSION}"
+    exit
+  end
+
+  opts.on('-h', '--help', 'Print this help') do
+    puts opts
+    exit
+  end
+end
+
+parser.parse!
+
+file = ARGV.shift
+
+if file.nil?
+  puts parser
+  exit 1
+end
+
+archive = Abbu.open(file)
+
+if options[:stats]
+  contacts = archive.contacts
+  puts "Total contacts : #{contacts.count}"
+  puts "With email     : #{contacts.count { |c| c.emails.any? }}"
+  puts "With phone     : #{contacts.count { |c| c.phones.any? }}"
+  exit
+end
+
+if options[:dedupe]
+  require 'abbu/utils/deduplicator'
+  dupes = Abbu::Utils::Deduplicator.new(archive.contacts).duplicates
+  if dupes.empty?
+    puts 'No duplicates found.'
+  else
+    dupes.each do |email, contacts|
+      puts "Duplicate: #{email}"
+      contacts.each { |c| puts "  - #{c.full_name}" }
+    end
+  end
+  exit
+end
+
+case options[:format]
+when 'csv'
+  exporter = Abbu::Exporters::CsvExporter.new(archive.contacts)
+  options[:output] ? exporter.to_file(options[:output]) : exporter.to_stdout
+when 'json'
+  exporter = Abbu::Exporters::JsonExporter.new(archive.contacts)
+  options[:output] ? exporter.to_file(options[:output]) : exporter.to_stdout
+when 'vcard'
+  exporter = Abbu::Exporters::VcardExporter.new(archive.contacts)
+  options[:output] ? exporter.to_file(options[:output]) : exporter.to_stdout
+else
+  puts parser
+  exit 1
+end

data/bin/cleanse

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# bin/cleanse
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+exec bundle exec rubocop -A "$@"

data/bin/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# bin/console
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require "irb"
+require "abbu"
+
+IRB.start(__FILE__)

data/bin/dev

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# bin/dev
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+exec bundle exec guard

data/bin/lint

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# bin/lint
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+exec bundle exec rubocop "$@"

data/bin/outdated

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# bin/outdated
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+exec bundle outdated "$@"

data/bin/test

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# bin/test
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+exec bundle exec rspec "$@"

data/docs/ABBU.md

@@ -0,0 +1,87 @@
+<!-- docs/ABBU.md -->
+
+# ABBU File Format (Apple Contacts Archive)
+
+## Overview
+
+`.abbu` files are exported from Apple Contacts.app and represent a full address book archive.
+
+They are **not** a single file format — they are a macOS "package" (a directory bundle that Finder
+presents as a single file). This means you can inspect the contents with `ls` or `open -a Finder`.
+
+## Structure
+
+Typical contents of a `.abbu` bundle:
+
+```text
+Contacts.abbu/
+├── AddressBook-v22.abcddb   ← SQLite database for "Local" contacts (often mostly empty)
+├── Metadata/                ← plist files (bundle metadata)
+│   └── *.abcdp
+├── Images/                  ← contact photos (JPEG/PNG)
+│   └── <uuid>.jpg
+├── Sources/                 ← Remote synced accounts (iCloud, Exchange, Google)
+│   ├── <account_uuid>/
+│   │   ├── AddressBook-v22.abcddb  ← SQLite database for this specific account
+│   │   ├── Metadata/
+│   │   └── Images/
+│   └── <another_uuid>/...
+└── Records/                 ← legacy plist-based contact records (older macOS)
+    └── <uuid>.abcdp
+```
+
+> **Note:** The most common pitfall when parsing `.abbu` files is only reading the root `AddressBook-v22.abcddb`. For users syncing via iCloud or Exchange, the root database will be nearly empty. Parsers must recursively scan the `Sources/` directory to discover and extract all contacts from all `.abcddb` files.
+
+## Formats
+
+### 1. SQLite (modern macOS)
+
+Newer macOS versions store the address book in a single SQLite database:
+
+```
+AddressBook-v22.abcddb
+```
+
+Key tables:
+
+| Table                  | Purpose                              |
+|------------------------|--------------------------------------|
+| `ZABCDRECORD`          | One row per contact (name, company)  |
+| `ZABCDEMAILADDRESS`    | Email addresses (linked by `ZOWNER`) |
+| `ZABCDPHONENUMBER`     | Phone numbers (linked by `ZOWNER`)   |
+
+Notable columns in `ZABCDRECORD`:
+
+| Column          | Description      |
+|-----------------|------------------|
+| `Z_PK`          | Primary key      |
+| `ZFIRSTNAME`    | First name       |
+| `ZLASTNAME`     | Last name        |
+| `ZORGANIZATION` | Company / org    |
+
+### 2. Plist / `.abcdp` (legacy macOS)
+
+Older macOS versions stored each contact as a separate binary plist file under `Records/`.
+Each file is a serialised `ABPerson` dictionary. The `abbu` gem currently stubs this parser
+and returns an empty array with a warning.
+
+## Export Steps
+
+To create a `.abbu` file:
+
+1. Open **Contacts.app** on macOS
+2. Select all contacts (`⌘A`)
+3. File → Export → **Export vCard** *(or)* File → Export → **Contacts Archive…**
+
+The "Contacts Archive" option produces a `.abbu` bundle.
+
+## References
+
+- [Apple Contacts Framework (private)](https://developer.apple.com/documentation/contacts)
+- [SQLite3 gem](https://github.com/sparklemotion/sqlite3-ruby)
+- macOS `AddressBook.framework` private headers (reverse-engineered)
+
+---
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/examples/deduplicate_contacts.rb

@@ -0,0 +1,25 @@
+# examples/deduplicate_contacts.rb
+# frozen_string_literal: true
+
+# Find duplicate contacts by email address
+#
+# Usage:
+#   bundle exec ruby examples/deduplicate_contacts.rb Contacts.abbu
+
+require 'abbu'
+require 'abbu/utils/deduplicator'
+
+archive = Abbu.open(ARGV[0] || 'Contacts.abbu')
+
+dupes = Abbu::Utils::Deduplicator.new(archive.contacts).duplicates
+
+if dupes.empty?
+  puts 'No duplicates found.'
+else
+  puts "Found #{dupes.size} duplicate email(s):\n\n"
+  dupes.each do |email, contacts|
+    puts "Duplicate: #{email}"
+    contacts.each { |c| puts "  - #{c.full_name}" }
+    puts
+  end
+end

data/examples/export_to_api.rb

@@ -0,0 +1,27 @@
+# examples/export_to_api.rb
+# frozen_string_literal: true
+
+# Sync contacts from a .abbu archive to a JSON API (CRM / Rodeo pattern)
+#
+# Usage:
+#   bundle exec ruby examples/export_to_api.rb Contacts.abbu
+
+require 'abbu'
+require 'net/http'
+require 'json'
+
+API_ENDPOINT = 'https://api.example.com/contacts'
+
+archive = Abbu.open(ARGV[0] || 'Contacts.abbu')
+
+archive.contacts.each do |c|
+  uri = URI(API_ENDPOINT)
+
+  response = Net::HTTP.post(
+    uri,
+    { name: c.full_name, email: c.emails.first, phone: c.phones.first }.to_json,
+    'Content-Type' => 'application/json'
+  )
+
+  puts "#{c.full_name} → #{response.code}"
+end

data/examples/export_to_csv.rb

@@ -0,0 +1,22 @@
+# examples/export_to_csv.rb
+# frozen_string_literal: true
+
+# Export all contacts from a .abbu archive to contacts.csv
+#
+# Usage:
+#   bundle exec ruby examples/export_to_csv.rb Contacts.abbu
+
+require 'abbu'
+require 'csv'
+
+archive = Abbu.open(ARGV[0] || 'Contacts.abbu')
+
+CSV.open('contacts.csv', 'w') do |csv|
+  csv << %w[Name Email Phone Company]
+
+  archive.contacts.each do |c|
+    csv << [c.full_name, c.emails.first, c.phones.first, c.company]
+  end
+end
+
+puts "Exported #{archive.contacts.count} contacts to contacts.csv"

data/examples/export_to_json.rb

@@ -0,0 +1,18 @@
+# examples/export_to_json.rb
+# frozen_string_literal: true
+
+# Export all contacts from a .abbu archive to contacts.json
+#
+# Usage:
+#   bundle exec ruby examples/export_to_json.rb Contacts.abbu
+#   bundle exec ruby examples/export_to_json.rb Contacts.abbu | jq .
+
+require 'abbu'
+
+archive = Abbu.open(ARGV[0] || 'Contacts.abbu')
+
+Abbu::Exporters::JsonExporter
+  .new(archive.contacts)
+  .to_file('contacts.json')
+
+puts "Exported #{archive.contacts.count} contacts to contacts.json"

data/examples/export_to_vcard.rb

@@ -0,0 +1,17 @@
+# examples/export_to_vcard.rb
+# frozen_string_literal: true
+
+# Export all contacts from a .abbu archive to contacts.vcf
+#
+# Usage:
+#   bundle exec ruby examples/export_to_vcard.rb Contacts.abbu
+
+require 'abbu'
+
+archive = Abbu.open(ARGV[0] || 'Contacts.abbu')
+
+Abbu::Exporters::VcardExporter
+  .new(archive.contacts)
+  .to_file('contacts.vcf')
+
+puts "Exported #{archive.contacts.count} contacts to contacts.vcf"

data/examples/stats_report.rb

@@ -0,0 +1,18 @@
+# examples/stats_report.rb
+# frozen_string_literal: true
+
+# Print a summary report of contacts in a .abbu archive
+#
+# Usage:
+#   bundle exec ruby examples/stats_report.rb Contacts.abbu
+
+require 'abbu'
+
+archive  = Abbu.open(ARGV[0] || 'Contacts.abbu')
+contacts = archive.contacts
+
+puts '=== Contacts Report ==='
+puts "Total contacts : #{contacts.count}"
+puts "With email     : #{contacts.count { |c| c.emails.any? }}"
+puts "With phone     : #{contacts.count { |c| c.phones.any? }}"
+puts "With company   : #{contacts.count(&:company)}"

data/examples/sync_to_crm.rb

@@ -0,0 +1,22 @@
+# examples/sync_to_crm.rb
+# frozen_string_literal: true
+
+# Stub CRM sync pattern — replace CRM.upsert with your adapter
+#
+# Usage:
+#   bundle exec ruby examples/sync_to_crm.rb Contacts.abbu
+
+require 'abbu'
+
+# Replace this class with your real CRM adapter (Printavo, HubSpot, Rodeo, etc.)
+class CRM
+  def self.upsert(contact)
+    puts "Syncing #{contact.full_name}"
+  end
+end
+
+archive = Abbu.open(ARGV[0] || 'Contacts.abbu')
+
+archive.contacts.each do |c|
+  CRM.upsert(c)
+end

data/lib/abbu/archive.rb

@@ -0,0 +1,47 @@
+# lib/abbu/archive.rb
+# frozen_string_literal: true
+
+require_relative 'parsers/sqlite_parser'
+require_relative 'parsers/plist_parser'
+
+module Abbu
+  class Archive
+    attr_reader :path
+
+    def initialize(path)
+      @path = Pathname.new(path)
+      validate!
+    end
+
+    def contacts
+      parser.contacts
+    end
+
+    def sqlite?
+      db_paths.any?
+    end
+
+    private
+
+    def validate!
+      raise ArgumentError, "ABBU path not found: #{@path}" unless @path.exist?
+      raise ArgumentError, "Not a directory bundle: #{@path}" unless @path.directory?
+    end
+
+    def db_paths
+      @db_paths ||= @path.glob('**/*.abcddb')
+    end
+
+    def records_path
+      @records_path ||= @path.join('Records')
+    end
+
+    def parser
+      if sqlite?
+        Parsers::SqliteParser.new(db_paths)
+      else
+        Parsers::PlistParser.new(records_path)
+      end
+    end
+  end
+end

data/lib/abbu/contact.rb

@@ -0,0 +1,26 @@
+# lib/abbu/contact.rb
+# frozen_string_literal: true
+
+module Abbu
+  class Contact
+    attr_accessor :first_name, :last_name, :emails, :phones, :company
+
+    def initialize
+      @emails = []
+      @phones = []
+    end
+
+    def full_name
+      [first_name, last_name].compact.join(' ')
+    end
+
+    def to_s
+      "#<Abbu::Contact first_name=#{first_name.inspect} last_name=#{last_name.inspect} " \
+        "emails=#{emails.inspect} phones=#{phones.inspect}>"
+    end
+
+    def inspect
+      to_s
+    end
+  end
+end

data/lib/abbu/exporters/csv_exporter.rb

@@ -0,0 +1,38 @@
+# lib/abbu/exporters/csv_exporter.rb
+# frozen_string_literal: true
+
+require 'csv'
+
+module Abbu
+  module Exporters
+    class CsvExporter
+      def initialize(contacts)
+        @contacts = contacts
+      end
+
+      def to_file(path)
+        CSV.open(path, 'w') do |csv|
+          csv << headers
+          @contacts.each { |c| csv << row(c) }
+        end
+      end
+
+      def to_stdout
+        puts(CSV.generate do |csv|
+          csv << headers
+          @contacts.each { |c| csv << row(c) }
+        end)
+      end
+
+      private
+
+      def headers
+        %w[Name Email Phone Company]
+      end
+
+      def row(contact)
+        [contact.full_name, contact.emails.first, contact.phones.first, contact.company]
+      end
+    end
+  end
+end

data/lib/abbu/exporters/json_exporter.rb

@@ -0,0 +1,35 @@
+# lib/abbu/exporters/json_exporter.rb
+# frozen_string_literal: true
+
+require 'json'
+
+module Abbu
+  module Exporters
+    class JsonExporter
+      def initialize(contacts)
+        @contacts = contacts
+      end
+
+      def to_file(path)
+        File.write(path, JSON.pretty_generate(payload))
+      end
+
+      def to_stdout
+        puts JSON.pretty_generate(payload)
+      end
+
+      private
+
+      def payload
+        @contacts.map do |c|
+          {
+            name: c.full_name,
+            emails: c.emails,
+            phones: c.phones,
+            company: c.company
+          }
+        end
+      end
+    end
+  end
+end

data/lib/abbu/exporters/vcard_exporter.rb

@@ -0,0 +1,37 @@
+# lib/abbu/exporters/vcard_exporter.rb
+# frozen_string_literal: true
+
+module Abbu
+  module Exporters
+    class VcardExporter
+      def initialize(contacts)
+        @contacts = contacts
+      end
+
+      def to_file(path)
+        File.write(path, generate)
+      end
+
+      def to_stdout
+        puts generate
+      end
+
+      private
+
+      def generate
+        @contacts.map { |c| vcard_for(c) }.join("\n")
+      end
+
+      def vcard_for(contact)
+        lines = ['BEGIN:VCARD', 'VERSION:3.0']
+        lines << "FN:#{contact.full_name}"
+        lines << "N:#{contact.last_name};#{contact.first_name};;;"
+        lines << "ORG:#{contact.company}" if contact.company
+        contact.emails.each { |e| lines << "EMAIL:#{e}" }
+        contact.phones.each { |p| lines << "TEL:#{p}" }
+        lines << 'END:VCARD'
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/abbu/parsers/plist_parser.rb

@@ -0,0 +1,17 @@
+# lib/abbu/parsers/plist_parser.rb
+# frozen_string_literal: true
+
+module Abbu
+  module Parsers
+    class PlistParser
+      def initialize(path)
+        @path = path
+      end
+
+      def contacts
+        warn 'Plist parsing not yet implemented — no .abcddb found in this archive.'
+        []
+      end
+    end
+  end
+end

data/lib/abbu/parsers/sqlite_parser.rb

@@ -0,0 +1,59 @@
+# lib/abbu/parsers/sqlite_parser.rb
+# frozen_string_literal: true
+
+require 'sqlite3'
+require_relative '../contact'
+
+module Abbu
+  module Parsers
+    class SqliteParser
+      def initialize(db_paths)
+        @db_paths = Array(db_paths)
+      end
+
+      def contacts
+        @db_paths.flat_map do |db_path|
+          parse_db(db_path)
+        end
+      end
+
+      private
+
+      def parse_db(db_path)
+        db = SQLite3::Database.new(db_path.to_s)
+        db.results_as_hash = true
+        records(db).map { |row| build_contact(db, row) }
+      ensure
+        db&.close
+      end
+
+      def records(db)
+        db.execute('SELECT * FROM ZABCDRECORD')
+      end
+
+      def emails_for(db, record_id)
+        db.execute(
+          'SELECT ZADDRESSNORMALIZED FROM ZABCDEMAILADDRESS WHERE ZOWNER = ?',
+          record_id
+        ).filter_map { |row| row['ZADDRESSNORMALIZED'] }
+      end
+
+      def phones_for(db, record_id)
+        db.execute(
+          'SELECT ZFULLNUMBER FROM ZABCDPHONENUMBER WHERE ZOWNER = ?',
+          record_id
+        ).filter_map { |row| row['ZFULLNUMBER'] }
+      end
+
+      def build_contact(db, row)
+        contact = Contact.new
+        contact.first_name = row['ZFIRSTNAME']
+        contact.last_name  = row['ZLASTNAME']
+        contact.company    = row['ZORGANIZATION']
+        contact.emails     = emails_for(db, row['Z_PK'])
+        contact.phones     = phones_for(db, row['Z_PK'])
+        contact
+      end
+    end
+  end
+end

data/lib/abbu/utils/deduplicator.rb

@@ -0,0 +1,19 @@
+# lib/abbu/utils/deduplicator.rb
+# frozen_string_literal: true
+
+module Abbu
+  module Utils
+    class Deduplicator
+      def initialize(contacts)
+        @contacts = contacts
+      end
+
+      def duplicates
+        @contacts
+          .group_by { |c| c.emails.first }
+          .reject    { |k, _| k.nil? }
+          .select    { |_, v| v.size > 1 }
+      end
+    end
+  end
+end

data/lib/abbu/version.rb

@@ -0,0 +1,6 @@
+# lib/abbu/version.rb
+# frozen_string_literal: true
+
+module Abbu
+  VERSION = '0.1.0'
+end

data/lib/abbu.rb

@@ -0,0 +1,18 @@
+# lib/abbu.rb
+# frozen_string_literal: true
+
+require_relative 'abbu/version'
+require_relative 'abbu/contact'
+require_relative 'abbu/archive'
+require_relative 'abbu/parsers/sqlite_parser'
+require_relative 'abbu/parsers/plist_parser'
+require_relative 'abbu/exporters/csv_exporter'
+require_relative 'abbu/exporters/json_exporter'
+require_relative 'abbu/exporters/vcard_exporter'
+require_relative 'abbu/utils/deduplicator'
+
+module Abbu
+  def self.open(path)
+    Archive.new(path)
+  end
+end

data/tasks/abbu.rake

@@ -0,0 +1,49 @@
+# tasks/abbu.rake
+# frozen_string_literal: true
+
+require 'abbu'
+require 'csv'
+
+namespace :abbu do
+  desc 'Export contacts to CSV — rake abbu:export[file=Contacts.abbu]'
+  task :export, [:file] do |_, args|
+    archive = Abbu.open(args[:file] || 'Contacts.abbu')
+
+    CSV.open('contacts.csv', 'w') do |csv|
+      csv << %w[Name Email Phone Company]
+      archive.contacts.each do |c|
+        csv << [c.full_name, c.emails.first, c.phones.first, c.company]
+      end
+    end
+
+    puts "Exported #{archive.contacts.count} contacts to contacts.csv"
+  end
+
+  desc 'Find duplicate contacts — rake abbu:dedupe[file=Contacts.abbu]'
+  task :dedupe, [:file] do |_, args|
+    require 'abbu/utils/deduplicator'
+
+    archive = Abbu.open(args[:file] || 'Contacts.abbu')
+    dupes   = Abbu::Utils::Deduplicator.new(archive.contacts).duplicates
+
+    if dupes.empty?
+      puts 'No duplicates found.'
+    else
+      dupes.each do |email, contacts|
+        puts "Duplicate: #{email}"
+        contacts.each { |c| puts "  - #{c.full_name}" }
+      end
+    end
+  end
+
+  desc 'Print contact stats — rake abbu:stats[file=Contacts.abbu]'
+  task :stats, [:file] do |_, args|
+    archive  = Abbu.open(args[:file] || 'Contacts.abbu')
+    contacts = archive.contacts
+
+    puts "Total contacts : #{contacts.count}"
+    puts "With email     : #{contacts.count { |c| c.emails.any? }}"
+    puts "With phone     : #{contacts.count { |c| c.phones.any? }}"
+    puts "With company   : #{contacts.count(&:company)}"
+  end
+end

metadata

@@ -0,0 +1,234 @@
+--- !ruby/object:Gem::Specification
+name: abbu
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stan Carver II
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.18'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+- !ruby/object:Gem::Dependency
+  name: guard-rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: Parse Apple Address Book Archive (.abbu) files and export contacts to
+  CSV, JSON, or vCard. Supports modern SQLite-backed archives and legacy plist-based
+  records.
+email:
+- stan@a1webconsulting.com
+executables:
+- abbu
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/abbu
+- bin/cleanse
+- bin/console
+- bin/dev
+- bin/lint
+- bin/outdated
+- bin/test
+- docs/ABBU.md
+- examples/deduplicate_contacts.rb
+- examples/export_to_api.rb
+- examples/export_to_csv.rb
+- examples/export_to_json.rb
+- examples/export_to_vcard.rb
+- examples/stats_report.rb
+- examples/sync_to_crm.rb
+- lib/abbu.rb
+- lib/abbu/archive.rb
+- lib/abbu/contact.rb
+- lib/abbu/exporters/csv_exporter.rb
+- lib/abbu/exporters/json_exporter.rb
+- lib/abbu/exporters/vcard_exporter.rb
+- lib/abbu/parsers/plist_parser.rb
+- lib/abbu/parsers/sqlite_parser.rb
+- lib/abbu/utils/deduplicator.rb
+- lib/abbu/version.rb
+- tasks/abbu.rake
+homepage: https://github.com/scarver2/abbu
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/scarver2/abbu
+  source_code_uri: https://github.com/scarver2/abbu
+  changelog_uri: https://github.com/scarver2/abbu/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Read and process Apple Contacts .abbu archives in Ruby.
+test_files: []