abbu 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9926de7b6edc99155f0ddf18c39ebfab80677152caeba28bc7b2bce8b0e870bd
-  data.tar.gz: 8c7c8224f7799343d8ac994e4c21c2185b30f53aa8bd87783c5423f2ee09d1d8
+  metadata.gz: e93fb2c992d75b467a430083bd474aef632c6f759ae858653e9b3ed44e261cc9
+  data.tar.gz: f346d67e1789116120ec804881b0f9660d6853c55102557e084d8be78184a0cf
 SHA512:
-  metadata.gz: 32b5f1d5496c8ae68f849756242588d6eac681305fee894156d1ba2a1717bb7e3b3fd8b03ce2504ff3c2340597451217a1b29fea9f7eb78e971d161c6b47072c
-  data.tar.gz: b1e62d48dca35bf1d3cb584728e7333f85c31971bcd28c01cc718949b8d093108c407efb159bbbf6017002fa3b6c2676c08906df8502fe1647ad6974787a9c9a
+  metadata.gz: ae3d1565ac2203067a1e2da4cb304eba8b112bfbd94b78f65c0a39a58f6a007835da1929fcfbc58cea13fdde43ac23eae1338b77fcf4466b31a2a2f40f31a3a6
+  data.tar.gz: 6a904be665a31a2254c139aced555dfcfd92af6612bec463ad776e5e99f939210954625c5141b17ee095518b0bd85d29f9dbfa795ec0f0ac34a9b8dd8231c6b0

data/README.md

@@ -2,18 +2,26 @@
 
 # abbu
 
-Read and process Apple Contacts `.abbu` archives in Ruby.
+Read-only Apple Contacts toolkit for `.abbu` archives and opt-in live macOS stores.
+Version 0.4.0 adds querying, diagnostics, identity evidence, and safe image extraction
+alongside CSV, JSON, and vCard export. The public API remains pre-1.0.
 
 ## Features
 
 - Parse ABBU (Apple Contacts export) bundles
+- Opt-in, read-only access to a local macOS Contacts store
 - SQLite-backed contact extraction (modern macOS)
 - Legacy plist `.abcdp` parsing (older macOS)
-- Full Apple Contacts schema: names, nicknames, prefix/suffix, job title, department, phonetics, pronouns, and more
+- Evidence-backed Apple Contacts fields: names, nicknames, prefix/suffix, job title, department, phonetics, pronouns, and more
 - Rich relational data: addresses, URLs, notes, related names, social profiles
 - Export to CSV, JSON, vCard 3.0
 - CLI + Ruby API
-- Duplicate detection
+- Source provenance and creation/modification timestamps
+- Lossless raw labels alongside human-friendly normalization
+- Schema introspection, tolerant diagnostics, and strict mode
+- Chainable archive queries, exact identifier lookup, and TSV/JSON CLI search
+- Provenance-aware duplicate suggestions without automatic merging
+- Safe photo extraction with content detection and no destination overwrites
 
 ## Installation
 
@@ -36,13 +44,66 @@ require "abbu"
 
 archive = Abbu.open("Contacts.abbu")
 contacts = archive.contacts
+schema = archive.schema_report # Evidence-only SQLite schema diagnostics
 
 contacts.first.full_name   # => "Honorable Stan \"Stretch\" Carver II"
-contacts.first.emails      # => [{ address: "stan@example.com", label: "Work" }]
-contacts.first.phones      # => [{ number: "555-1234", label: "Mobile" }]
+contacts.first.emails      # => [{ address: "stan@example.com", label: "Work", raw_label: "_$!<Work>!$_" }]
+contacts.first.phones      # => [{ number: "555-1234", label: "Mobile", raw_label: "Mobile" }]
 contacts.first.job_title   # => "Engineer"
+
+# Copy resolved photos using safe, content-derived filenames.
+result = archive.extract_images("exported-photos")
+result.files        # copied-file metadata, including source_path and media_type
+result.diagnostics  # image errors or destination_exists; may contain contact identifiers
+
+# Recover safe records and inspect non-fatal data loss.
+archive.diagnostics.each { |diagnostic| warn diagnostic.to_h }
+
+# Or fail on the first corrupt/unsupported optional input.
+strict_contacts = Abbu.open("Contacts.abbu", strict: true).contacts
+```
+
+Live-store access is a separate, explicit API and never changes `Abbu.open` archive
+validation:
+
+```ruby
+# Auto-discover the current macOS user's AddressBook directory
+live_contacts = Abbu.open_live.contacts
+
+# Or supply a directory for automation and platform-independent testing
+live_contacts = Abbu.open_live("/path/to/AddressBook").contacts
+```
+
+Live databases are opened with SQLite's read-only mode. The process may require
+Full Disk Access under **System Settings → Privacy & Security → Full Disk Access**.
+Live inputs expose parser `diagnostics` and accept `strict: true` (CLI `--strict`).
+The live CLI supports stats, deduplication, and exports; archive-only search, schema,
+and image-extraction options are rejected explicitly.
+
+Live access does not write Contacts databases. WAL/concurrent-writer consistency
+remains unverified ([#28](https://github.com/scarver2/abbu/issues/28)).
+
+Labeled values expose a normalized `label` for display and retain the source
+value in `raw_label`. For example, `_$!<Mobile>!$_` becomes `Mobile` while the
+original wrapper remains available in `raw_label`.
+
+### Search and identifier lookup
+
+```ruby
+# Exact lookup normalizes email case/whitespace and phone punctuation.
+archive.find_by_email("STAN@EXAMPLE.COM").each { |contact| puts contact.full_name }
+archive.find_by_phone("(555) 123-4567").each { |contact| puts contact.full_name }
+
+# Name and email search is case-insensitive and can be chained with `where`.
+archive.where(company: "Acme Corp").search("stan").each do |contact|
+  puts [contact.full_name, contact.source[:relative_path]].join("\t")
+end
 ```
 
+Lookup methods return every match as an `Abbu::Query`; they never silently pick
+one contact when the same identifier appears in multiple sources. Returned
+contacts retain their parser-provided source provenance.
+
 ### Export
 
 ```ruby
@@ -66,6 +127,23 @@ dupes.each do |email, contacts|
 end
 ```
 
+For provenance-aware suggestions, use `#matches`. Results preserve both contacts,
+their source records, raw and normalized evidence, confidence, and ambiguity:
+
+```ruby
+matches = Abbu::Utils::Deduplicator.new(archive.contacts).matches
+matches.each do |match|
+  puts "#{match.confidence}: #{match.left.full_name} / #{match.right.full_name}"
+  pp match.sources
+  pp match.evidence
+end
+
+# Matching never mutates or collapses contacts. Merging requires a caller policy:
+merged = matches.first.merge(policy: ->(left, right, evidence:) {
+  MyContactMerge.call(left, right, evidence: evidence)
+})
+```
+
 ## CLI
 
 ```bash
@@ -78,13 +156,41 @@ abbu Contacts.abbu -f json | jq .
 # vCard export
 abbu Contacts.abbu -f vcard -o contacts.vcf
 
+# Copy contact photos to a selected directory
+abbu Contacts.abbu --extract-images exported-photos
+
 # Stats
 abbu Contacts.abbu --stats
 
 # Find duplicates
 abbu Contacts.abbu --dedupe
+
+# Read the current macOS user's live Contacts store
+abbu --live --stats
+
+# Read a caller-supplied AddressBook directory
+abbu --live-path /path/to/AddressBook -f json
+
+# Fail on the first corrupt or unsupported optional record/table.
+abbu Contacts.abbu --stats --strict
+
+# Inspect each SQLite schema without inferring undocumented semantics
+abbu Contacts.abbu --schema
+
+# Tab-separated search output: name, emails, phones, source-relative path
+abbu Contacts.abbu --search stan
+abbu Contacts.abbu --email stan@example.com
+abbu Contacts.abbu --phone '(555) 123-4567'
+
+# Stable structured search output using the regular contact JSON schema
+abbu Contacts.abbu --search stan --json | jq .
 ```
 
+CLI search defaults to tab-separated output and exits successfully when at least
+one contact matches. A search with no matches exits with status 1; TSV mode emits
+no output, while `--json` emits a valid empty array. This makes both modes
+suitable for shell conditionals, pipelines, and agent integrations.
+
 ## Rake Tasks
 
 ```ruby
@@ -107,13 +213,19 @@ SQLite table schema, and format history.
 
 See [`docs/TODO.md`](docs/TODO.md) for the full release schedule and feature checklist.
 
+## Ruby Compatibility
+
+`abbu` supports Ruby 3.3 and newer. CI exercises Ruby 3.3, 3.4, and 4.0;
+Ruby 3.3 is the compatibility floor and designated lint/tooling job.
+
 ## 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
+bin/dev      # Guard feedback loop
+bin/spec     # RSpec with the 100% coverage gate
+bin/lint     # RuboCop
+bin/package  # build and verify the gem in isolation
 ```
 
 ## Contributing

data/bin/abbu

@@ -4,90 +4,221 @@
 
 $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 
+require 'json'
 require 'optparse'
 require 'abbu'
 
 options = {
   format: nil,
   output: nil,
+  extract_images: nil,
   dedupe: false,
-  stats: false
+  email: nil,
+  json: false,
+  live: nil,
+  live_path: nil,
+  phone: nil,
+  search: nil,
+  schema: false,
+  stats: false,
+  strict: false
 }
 
-parser = OptionParser.new do |opts|
-  opts.banner = 'Usage: abbu <file.abbu> [options]'
+parser = OptionParser.new
+parser.banner = 'Usage: abbu <file.abbu> [options] | abbu --live [options] | abbu --live-path PATH [options]'
 
-  opts.on('-f', '--format FORMAT', %w[csv json vcard], 'Export format (csv, json, vcard)') do |f|
-    options[:format] = f
-  end
+parser.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
+parser.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
+parser.on('--extract-images DIR', 'Copy contact images to DIR') do |dir|
+  options[:extract_images] = dir
+end
 
-  opts.on('--dedupe', 'Find and print duplicate contacts') do
-    options[:dedupe] = true
-  end
+parser.on('--stats', 'Print contact statistics') do
+  options[:stats] = true
+end
 
-  opts.on('-v', '--version', 'Print version') do
-    puts "abbu #{Abbu::VERSION}"
-    exit
-  end
+parser.on('--dedupe', 'Find and print duplicate contacts') do
+  options[:dedupe] = true
+end
 
-  opts.on('-h', '--help', 'Print this help') do
-    puts opts
-    exit
-  end
+parser.on('--search TERM', 'Find contacts by partial name or email') do |term|
+  options[:search] = term
+end
+
+parser.on('--strict', 'Raise on unsupported or corrupt optional data') do
+  options[:strict] = true
+end
+
+parser.on('--schema', 'Print SQLite schema diagnostics as JSON') do
+  options[:schema] = true
+end
+
+parser.on('--email ADDRESS', 'Find contacts by exact normalized email') do |address|
+  options[:email] = address
+end
+
+parser.on('--phone NUMBER', 'Find contacts by exact normalized phone number') do |number|
+  options[:phone] = number
+end
+
+parser.on('--json', 'Emit search results as structured JSON instead of TSV') do
+  options[:json] = true
+end
+
+parser.on('-v', '--version', 'Print version') do
+  puts "abbu #{Abbu::VERSION}"
+  exit
+end
+
+parser.on('-h', '--help', 'Print this help') do
+  puts parser
+  exit
+end
+
+parser.on('--live', 'Auto-discover the current macOS Contacts store') do
+  options[:live] = true
+end
+
+parser.on('--live-path PATH', 'Read the specified live AddressBook directory') do |path|
+  options[:live_path] = path
 end
 
 parser.parse!
 
+live_mode = options[:live] || !options[:live_path].nil?
+live_path = options[:live_path]
+
+if options[:live] && live_path
+  warn 'Use only one of --live or --live-path PATH.'
+  exit 1
+end
+
+if live_mode && ARGV.any?
+  warn 'Unexpected positional arguments in live mode; use --live-path PATH for an explicit store.'
+  exit 1
+end
+
 file = ARGV.shift
 
-if file.nil?
+if file.nil? && !live_mode
   puts parser
   exit 1
 end
 
-archive = Abbu.open(file)
+archive = nil
 
-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
+at_exit do
+  next if archive.nil? || archive.diagnostics.empty?
+
+  warn "Diagnostics: #{archive.diagnostics.count}"
+  archive.diagnostics.each do |diagnostic|
+    warn "- #{diagnostic.category}: #{diagnostic.message} [#{diagnostic.source}]"
+  end
 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}" }
+begin
+  if live_mode && options.values_at(:extract_images, :schema, :search, :email, :phone, :json).any?
+    warn '--live supports --stats, --dedupe, --format, and --strict; archive-only options are not supported.'
+    exit 1
+  end
+  archive = live_mode ? Abbu.open_live(live_path, strict: options[:strict]) : Abbu.open(file, strict: options[:strict])
+
+  if options[:extract_images]
+    result = archive.extract_images(options[:extract_images])
+    puts "Extracted #{result.files.count} image(s) to #{File.expand_path(options[:extract_images])}"
+    result.diagnostics.each do |diagnostic|
+      warn "Image #{diagnostic[:code]}: #{diagnostic[:contact_name]} (#{diagnostic[:image_uri]})"
     end
+    exit unless options[:format] || options[:stats] || options[:dedupe]
   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
+  if options[:schema]
+    puts JSON.pretty_generate(archive.schema_report)
+    exit
+  end
+
+  search_options = options.values_at(:search, :email, :phone).compact
+  if search_options.length > 1
+    warn 'Use only one of --search, --email, or --phone.'
+    exit 1
+  end
+
+  if options[:json] && search_options.empty?
+    warn '--json requires --search, --email, or --phone.'
+    exit 1
+  end
+
+  if search_options.any?
+    results = if options[:search]
+                archive.search(options[:search])
+              elsif options[:email]
+                archive.find_by_email(options[:email])
+              else
+                archive.find_by_phone(options[:phone])
+              end
+
+    if options[:json]
+      Abbu::Exporters::JsonExporter.new(results).to_stdout
+    else
+      results.each do |contact|
+        fields = [
+          contact.full_name,
+          contact.emails.filter_map { |email| email[:address] }.join(','),
+          contact.phones.filter_map { |phone| phone[:number] }.join(','),
+          contact.source&.fetch(:relative_path, nil)
+        ]
+        puts fields.map { |field| field.to_s.gsub(/[\t\r\n]/, ' ') }.join("\t")
+      end
+    end
+    exit(results.any? ? 0 : 1)
+  end
+
+  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
+rescue Abbu::LiveStore::Error => e
+  warn "abbu: #{e.message}"
   exit 1
+rescue Abbu::ParseError => e
+  warn "abbu: #{e.message}"
+  exit 2
 end