abbu 0.8.1 → 0.18.0

data/lib/abbu/exporters/sqlite_schema.rb

@@ -0,0 +1,76 @@
+# lib/abbu/exporters/sqlite_schema.rb
+# frozen_string_literal: true
+
+module Abbu
+  module Exporters
+    # Fixed ABBU-owned identifiers; source strings never become SQL identifiers.
+    module SqliteSchema
+      VERSION = 1
+      CONTACT_FIELDS = %i[first_name middle_name last_name nickname prefix suffix company job_title department
+                          maiden_name phonetic_first_name phonetic_middle_name phonetic_last_name phonetic_company
+                          pronouns ringtone texttone verification_code image_uri image_path].freeze
+      COLLECTIONS = {
+        emails: %i[address label raw_label], phones: %i[number label raw_label],
+        addresses: %i[street city state zip country label raw_label], urls: %i[url label raw_label],
+        related_names: %i[name label raw_label], social_profiles: %i[service username],
+        instant_messages: %i[address service label raw_label]
+      }.transform_values(&:freeze).freeze
+      DATE_FIELDS = %i[birthday anniversary lunar_birthday dates].freeze
+
+      module_function
+
+      def create(db)
+        db.execute('PRAGMA foreign_keys = ON')
+        db.execute("PRAGMA user_version = #{VERSION}")
+        db.execute('CREATE TABLE metadata (schema_version INTEGER NOT NULL, generator_version TEXT NOT NULL)')
+        db.execute('CREATE TABLE sources (id INTEGER PRIMARY KEY, path TEXT, relative_path TEXT, kind TEXT, ' \
+                   'identifier TEXT, evidence_json TEXT NOT NULL)')
+        create_contacts(db)
+        create_collections(db)
+        create_scalar_collections(db)
+        create_dates(db)
+        create_groups(db)
+      end
+
+      def create_contacts(db)
+        fields = CONTACT_FIELDS.map { |name| "#{name} TEXT" }.join(', ')
+        db.execute('CREATE TABLE contacts (id INTEGER PRIMARY KEY, source_id INTEGER REFERENCES sources(id), ' \
+                   "#{fields}, " \
+                   'created_at TEXT, modified_at TEXT, evidence_json TEXT NOT NULL)')
+        db.execute('CREATE INDEX contacts_source ON contacts(source_id)')
+      end
+
+      def create_collections(db)
+        COLLECTIONS.each do |table, columns|
+          fields = columns.map { |name| "#{name} TEXT" }.join(', ')
+          db.execute("CREATE TABLE #{table} (contact_id INTEGER NOT NULL REFERENCES contacts(id), " \
+                     "position INTEGER NOT NULL, #{fields}, evidence_json TEXT NOT NULL, " \
+                     'PRIMARY KEY(contact_id, position))')
+        end
+      end
+
+      def create_scalar_collections(db)
+        %w[notes group_labels].each do |table|
+          db.execute("CREATE TABLE #{table} (contact_id INTEGER NOT NULL REFERENCES contacts(id), " \
+                     'position INTEGER NOT NULL, value TEXT, evidence_json TEXT NOT NULL, ' \
+                     'PRIMARY KEY(contact_id, position))')
+        end
+      end
+
+      def create_dates(db)
+        db.execute('CREATE TABLE dates (contact_id INTEGER NOT NULL REFERENCES contacts(id), field TEXT NOT NULL, ' \
+                   'position INTEGER NOT NULL, year INTEGER, month INTEGER, day INTEGER, label TEXT, raw_label TEXT, ' \
+                   'evidence_json TEXT NOT NULL, PRIMARY KEY(contact_id, field, position))')
+      end
+
+      def create_groups(db)
+        db.execute('CREATE TABLE groups (id INTEGER PRIMARY KEY, source_id INTEGER REFERENCES sources(id), ' \
+                   'record_id INTEGER, name TEXT, evidence_json TEXT NOT NULL)')
+        db.execute('CREATE TABLE group_memberships (contact_id INTEGER NOT NULL REFERENCES contacts(id), ' \
+                   'position INTEGER NOT NULL, group_id INTEGER NOT NULL REFERENCES groups(id), ' \
+                   'PRIMARY KEY(contact_id, position))')
+        db.execute('CREATE INDEX memberships_group ON group_memberships(group_id)')
+      end
+    end
+  end
+end

data/lib/abbu/exporters/vcard_exporter.rb

@@ -1,15 +1,15 @@
 # lib/abbu/exporters/vcard_exporter.rb
 # frozen_string_literal: true
 
-require 'uri'
-
 require_relative 'vcard_document'
+require_relative 'vcard_photo'
 
 module Abbu
   module Exporters
     class VcardExporter
-      def initialize(contacts)
+      def initialize(contacts, photo_mode: :uri)
         @contacts = contacts
+        @photo = VcardPhoto.new(photo_mode)
       end
 
       def to_file(path)
@@ -20,6 +20,11 @@ module Abbu
         print generate
       end
 
+      def write_to(io)
+        @contacts.each { |contact| io.write(vcard_for(contact)) }
+        nil
+      end
+
       private
 
       def generate
@@ -81,14 +86,8 @@ module Abbu
       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)
+        property = @photo.property(contact)
+        lines << property if property
       end
 
       def append_notes(lines, contact)

data/lib/abbu/exporters/vcard_photo.rb

@@ -0,0 +1,50 @@
+# lib/abbu/exporters/vcard_photo.rb
+# frozen_string_literal: true
+
+require 'uri'
+
+module Abbu
+  module Exporters
+    # Serialization only: never resolves Apple image identifiers or converts bytes.
+    class VcardPhoto
+      def initialize(mode)
+        raise ArgumentError, 'photo_mode must be :uri or :embedded' unless %i[uri embedded].include?(mode)
+
+        @mode = mode
+      end
+
+      def property(contact)
+        path = contact.image_path
+        return embedded(contact) if @mode == :embedded
+        return unless path
+
+        escaped = URI::DEFAULT_PARSER.escape(path.to_s)
+        "PHOTO;VALUE=URI:#{URI::Generic.build(scheme: 'file', path: escaped)}"
+      end
+
+      private
+
+      def embedded(contact)
+        return unless contact.image_path || contact.image_uri
+
+        path = contact.image_path
+        raise ArgumentError, 'embedded photo is missing' unless path && File.file?(path)
+
+        bytes = File.binread(path)
+        type = image_type(bytes)
+        raise ArgumentError, 'embedded photo has unsupported content (HEIC is not supported)' unless type
+
+        "PHOTO;ENCODING=b;TYPE=#{type}:#{[bytes].pack('m0')}"
+      rescue IOError, SystemCallError
+        raise ArgumentError, 'embedded photo is unreadable'
+      end
+
+      def image_type(bytes)
+        return 'JPEG' if bytes.start_with?("\xFF\xD8\xFF".b)
+        return 'PNG' if bytes.start_with?("\x89PNG\r\n\x1A\n".b)
+
+        'GIF' if bytes.start_with?('GIF87a', 'GIF89a')
+      end
+    end
+  end
+end

data/lib/abbu/history_tracker.rb

@@ -0,0 +1,96 @@
+# lib/abbu/history_tracker.rb
+# frozen_string_literal: true
+
+require_relative 'snapshot_diff'
+
+module Abbu
+  class HistoryTracker
+    def initialize(retention:, max_pairs:, max_contacts:)
+      @retention = retention
+      @max_pairs = max_pairs
+      @max_contacts = max_contacts
+      @pool = []
+      @next_id = 0
+    end
+
+    def advance(contacts, snapshot)
+      raise ArgumentError, 'snapshot exceeds max_contacts' if contacts.length > @max_contacts
+
+      diff = SnapshotDiff.new(@pool.map { |entry| entry[:contact] }, contacts, max_pairs: @max_pairs).to_h
+      current, observations = observations_for(diff, contacts, snapshot)
+      absent = absent_for(diff, snapshot)
+      ambiguity = ambiguity_for(diff)
+      retain(diff, current, snapshot)
+      { schema_version: 1, snapshot: snapshot, observations: observations.freeze,
+        absent: absent.freeze, ambiguous: ambiguity.freeze }.freeze
+    end
+
+    private
+
+    def ambiguity_for(diff)
+      diff[:ambiguous].map do |pair|
+        pair.merge(before_timeline_id: @pool.fetch(pair[:before_index])[:timeline_id]).freeze
+      end
+    end
+
+    def observations_for(diff, contacts, snapshot)
+      lookups = record_lookups(diff)
+      @current = []
+      observations = contacts.each_with_index.map do |contact, index|
+        observe_contact(contact, index, snapshot, lookups)
+      end
+      [@current, observations]
+    end
+
+    def record_lookups(diff)
+      { pairs: (diff[:changed] + diff[:unchanged]).to_h { |pair| [pair[:after_index], pair] },
+        added: diff[:added].to_h { |item| [item[:index], item[:contact]] },
+        uncertain: diff[:ambiguous].to_h { |pair| [pair[:after_index], pair[:after]] } }
+    end
+
+    def observe_contact(contact, index, snapshot, lookups)
+      pair = lookups[:pairs][index]
+      previous = pair && @pool.fetch(pair[:before_index])
+      entry = track(contact, previous, snapshot)
+      @current << entry
+      record = lookups[:added][index] || lookups[:uncertain][index]
+      observation(entry, pair, record, previous, lookups[:uncertain].key?(index))
+    end
+
+    def track(contact, previous, snapshot)
+      @next_id += 1 unless previous
+      { contact: contact, timeline_id: previous ? previous[:timeline_id] : @next_id,
+        first_seen: previous ? previous[:first_seen] : snapshot, last_seen: snapshot }
+    end
+
+    def observation(entry, pair, record, previous, ambiguous)
+      details = { event: event_for(entry, previous, ambiguous), contact: pair ? pair[:after] : record,
+                  changes: pair ? pair[:fields] : {}.freeze, compared_with: previous && previous[:last_seen] }
+      details[:match] = pair&.slice(:score, :evidence)&.freeze
+      entry.except(:contact).merge(details).freeze
+    end
+
+    def event_for(entry, previous, ambiguous)
+      return ambiguous ? :ambiguous_start : :first_seen unless previous
+
+      previous[:last_seen][:index] < entry[:last_seen][:index] - 1 ? :reappeared : :observed
+    end
+
+    def absent_for(diff, snapshot)
+      diff[:removed].filter_map do |item|
+        entry = @pool.fetch(item[:index])
+        next unless entry[:last_seen][:index] == snapshot[:index] - 1
+
+        entry.except(:contact).merge(event: :absent, observed_at: snapshot).freeze
+      end
+    end
+
+    def retain(diff, current, snapshot)
+      removed = diff[:removed].map { |item| @pool.fetch(item[:index]) }
+      dormant = removed.select { |entry| snapshot[:index] - entry[:last_seen][:index] <= @retention }
+      @pool = current + dormant
+      raise ArgumentError, 'retained history exceeds max_contacts' if @pool.length > @max_contacts
+    end
+  end
+  private_constant :HistoryTracker
+end

data/lib/abbu/live_store.rb

@@ -42,6 +42,17 @@ module Abbu
       raise permission_error(e.message)
     end
 
+    def each_contact(&block)
+      return enum_for(:each_contact) unless block
+
+      Parsers::SqliteParser.new(
+        database_paths, root_path: @path, readonly: true, diagnostics: diagnostics, strict: @strict
+      ).each_contact(&block)
+      self
+    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?

data/lib/abbu/machine_command.rb

@@ -0,0 +1,159 @@
+# lib/abbu/machine_command.rb
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'machine_output'
+require_relative 'merge_preview'
+
+module Abbu
+  # One JSON document per invocation. Existing human CLI paths stay separate.
+  class MachineCommand
+    OPERATIONS = %i[stats schema sources groups dedupe matches diagnostics extract_images diff].freeze
+    SEARCHES = %i[search email phone].freeze
+
+    def initialize(options, arguments, stdout: $stdout, stderr: $stderr)
+      @options = options
+      @arguments = arguments
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    def run
+      @input = @comparison_input = nil
+      validate!
+      @input = open_input
+      print_result
+    rescue LiveStore::Error, SystemCallError, IOError => e
+      failure('input_output_error', e, 1)
+    rescue ParseError, ArgumentError => e
+      failure('invalid_input', e, 2)
+    ensure
+      report_diagnostics
+    end
+
+    private
+
+    def print_result
+      payload = execute
+      emit(payload)
+      search? && payload.empty? ? 1 : 0
+    end
+
+    def open_input
+      return Abbu.open_live(@options[:live_path], strict: @options[:strict]) if live?
+
+      Abbu.open(@arguments.first, strict: @options[:strict])
+    end
+
+    def live?
+      @options[:live] || @options[:live_path]
+    end
+
+    def search?
+      SEARCHES.any? { |key| @options[key] } || @options[:date_filters]
+    end
+
+    def operation
+      OPERATIONS.find { |key| @options[key] }
+    end
+
+    def validate!
+      raise ArgumentError, '--history requires standalone JSON Lines output' if @options[:history]
+
+      raise ArgumentError, '--stream requires a standalone CSV, JSONL or vCard export' if @options[:stream]
+
+      MergePreview.validate!(@options.merge(json: true))
+      validate_input!
+      validate_operation!
+      return unless live? && (search? || %i[schema extract_images].include?(operation))
+
+      raise ArgumentError, 'Search, schema, and image extraction require an archive input'
+    end
+
+    def validate_input!
+      raise ArgumentError, 'Use only one live input selector' if @options[:live] && @options[:live_path]
+      return if live? ? @arguments.empty? : @arguments.length == 1
+
+      raise ArgumentError, 'Provide exactly one archive path, or a live input selector without positional arguments'
+    end
+
+    def validate_operation!
+      count = OPERATIONS.count { |key| @options[key] } + (search? ? 1 : 0)
+      if count > 1 || SEARCHES.count { |key| @options[key] } > 1
+        raise ArgumentError, 'Choose only one machine operation (timestamp filters may accompany one search)'
+      end
+
+      validate_format!(count)
+    end
+
+    def validate_format!(count)
+      if @options.values_at(:calendar_year, :calendar_stamp, :calendar_id).any?
+        raise ArgumentError, 'Calendar options require a standalone iCalendar export'
+      end
+
+      incompatible_format = @options[:format] && (@options[:format] != 'json' || count.positive?)
+      return unless @options[:output] || @options[:photo_mode] || incompatible_format
+
+      raise ArgumentError, 'Machine output requires stdout JSON; file exports and photo options are separate operations'
+    end
+
+    def execute
+      output = MachineOutput.new(@input)
+      return output.contacts(query) if search?
+      return listing if %i[schema sources groups].include?(operation)
+
+      case operation
+      when :diff then snapshot_diff
+      when :extract_images then output.images(@options[:extract_images])
+      when :dedupe then output.duplicates
+      when nil then output.contacts
+      else output.public_send(operation)
+      end
+    end
+
+    def snapshot_diff
+      @comparison_input = Abbu.open(@options[:diff], strict: @options[:strict])
+      SnapshotDiff.new(@input, @comparison_input).to_h
+    end
+
+    def listing
+      return @input.schema_report if operation == :schema
+
+      @input.public_send(operation).map(&:to_h)
+    end
+
+    def query
+      results = initial_query
+      @options.fetch(:date_filters, {}).each { |field, bounds| results = results.date_range(field, **bounds) }
+      results
+    end
+
+    def initial_query
+      return @input.search(@options[:search]) if @options[:search]
+      return @input.find_by_email(@options[:email]) if @options[:email]
+      return @input.find_by_phone(@options[:phone]) if @options[:phone]
+
+      @input.query
+    end
+
+    def emit(payload)
+      @stdout.puts(JSON.pretty_generate(payload))
+    end
+
+    def failure(code, error, status)
+      emit(error: { code: code, message: error.message })
+      status
+    end
+
+    def report_diagnostics
+      if @comparison_input && !@comparison_input.diagnostics.empty?
+        @stderr.puts("Comparison input diagnostics: #{@comparison_input.diagnostics.length}")
+      end
+      return unless @input && operation != :diagnostics
+
+      @input.diagnostics.each do |diagnostic|
+        @stderr.puts("- #{diagnostic.category}: #{diagnostic.message} [#{diagnostic.source}]")
+      end
+    end
+  end
+end

data/lib/abbu/machine_output.rb

@@ -0,0 +1,52 @@
+# lib/abbu/machine_output.rb
+# frozen_string_literal: true
+
+require_relative 'exporters/json_exporter'
+require_relative 'utils/deduplicator'
+
+module Abbu
+  # Serialization only: no new identity inference, parser rules, or image reads.
+  class MachineOutput
+    def initialize(input)
+      @input = input
+    end
+
+    def contacts(records = @input.contacts)
+      Exporters::JsonExporter.new(records).payload
+    end
+
+    def stats
+      records = @input.contacts
+      { total_contacts: records.count, with_email: records.count { |c| c.emails.any? },
+        with_phone: records.count { |c| c.phones.any? } }
+    end
+
+    def diagnostics
+      @input.contacts
+      @input.diagnostics.map(&:to_h)
+    end
+
+    def duplicates
+      Utils::Deduplicator.new(@input.contacts).duplicates.map do |email, records|
+        { email: email, contacts: contacts(records) }
+      end
+    end
+
+    def matches
+      Utils::Deduplicator.new(@input.contacts).matches.map do |match|
+        { left: contacts([match.left]).first, right: contacts([match.right]).first,
+          sources: match.sources, evidence: match.evidence, score: match.score,
+          confidence: match.confidence, status: match.status }
+      end
+    end
+
+    def images(destination)
+      result = @input.extract_images(destination)
+      files = result.files.map do |record|
+        record.merge(contact: contacts([record[:contact]]).first,
+                     source_path: record[:source_path].to_s, path: record[:path].to_s)
+      end
+      { files: files, diagnostics: result.diagnostics }
+    end
+  end
+end

data/lib/abbu/mcp/read_session.rb

@@ -0,0 +1,57 @@
+# lib/abbu/mcp/read_session.rb
+# frozen_string_literal: true
+
+module Abbu
+  module Mcp
+    # One explicitly selected input, cached by ABBU's public input API. No tool
+    # may change its path, discover another store, export files, or apply edits.
+    class ReadSession
+      def initialize(input)
+        @input = input
+        @output = MachineOutput.new(input)
+      end
+
+      def query(mode:, value:, offset: 0, limit: 100)
+        validate_page!(offset, limit)
+        records = selection(mode, value).to_a
+        page = records.slice(offset, limit) || []
+        { contacts: @output.contacts(page), offset: offset, limit: limit, has_more: offset + limit < records.length }
+      end
+
+      def stats
+        @output.stats
+      end
+
+      def diagnostics
+        @output.diagnostics
+      end
+
+      def sources
+        @input.sources.map(&:to_h)
+      end
+
+      def groups
+        @input.groups.map(&:to_h)
+      end
+
+      private
+
+      def selection(mode, value)
+        query = Query.new(@input.contacts)
+        case mode
+        when 'search' then query.search(value)
+        when 'email' then query.find_by_email(value)
+        when 'phone' then query.find_by_phone(value)
+        when 'modified_since' then query.modified_since(value)
+        else raise ArgumentError, 'Unsupported query mode'
+        end
+      end
+
+      def validate_page!(offset, limit)
+        return if offset.is_a?(Integer) && offset >= 0 && limit.is_a?(Integer) && limit.between?(1, 500)
+
+        raise ArgumentError, 'offset must be nonnegative and limit must be between 1 and 500'
+      end
+    end
+  end
+end

data/lib/abbu/mcp/server.rb

@@ -0,0 +1,100 @@
+# lib/abbu/mcp/server.rb
+# frozen_string_literal: true
+
+require 'json'
+
+module Abbu
+  module Mcp
+    # SDK owns protocol validation/transport; this adapter only exposes an
+    # allowlist over public ABBU read APIs. No contact or request logging.
+    class Server
+      EMPTY_SCHEMA = { type: 'object', properties: {}, additionalProperties: false }.freeze
+      QUERY_SCHEMA = {
+        type: 'object', additionalProperties: false,
+        properties: {
+          mode: { type: 'string', enum: %w[search email phone modified_since] },
+          value: { type: 'string' }, offset: { type: 'integer', minimum: 0 },
+          limit: { type: 'integer', minimum: 1, maximum: 500 }
+        }, required: %w[mode value]
+      }.freeze
+      ARRAY_DATA = { type: 'array', items: { type: 'object' } }.freeze
+      DATA_SCHEMAS = {
+        query: {
+          type: 'object', properties: {
+            contacts: ARRAY_DATA, offset: { type: 'integer' }, limit: { type: 'integer' }, has_more: { type: 'boolean' }
+          }, required: %w[contacts offset limit has_more], additionalProperties: false
+        },
+        stats: {
+          type: 'object', properties: {
+            total_contacts: { type: 'integer' }, with_email: { type: 'integer' }, with_phone: { type: 'integer' }
+          }, required: %w[total_contacts with_email with_phone], additionalProperties: false
+        }
+      }.freeze
+      ANNOTATIONS = {
+        read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false
+      }.freeze
+      DESCRIPTIONS = {
+        query: 'Read sensitive contacts by name/email search, exact email/phone, or modified-since timestamp.',
+        stats: 'Read contact counts from the configured input.',
+        sources: 'Read observed source metadata; includes sensitive local paths and identifiers.',
+        groups: 'Read observed group metadata; includes sensitive group names and provenance.',
+        diagnostics: 'Read parser diagnostics; includes sensitive local paths, without full contact records.'
+      }.freeze
+
+      attr_reader :server
+
+      def initialize(path:, live: false, strict: false)
+        raise ArgumentError, 'An explicit nonempty path is required' unless path.is_a?(String) && !path.strip.empty?
+
+        input = live ? Abbu.open_live(path, strict: strict) : Abbu.open(path, strict: strict)
+        @session = ReadSession.new(input)
+        @server = ::MCP::Server.new(name: 'abbu', version: VERSION, tools: tools, configuration: configuration)
+      end
+
+      def open
+        ::MCP::Server::Transports::StdioTransport.new(server).open
+      end
+
+      private
+
+      def configuration
+        # SDK 1.6.1 validates successful structured content; isError results are
+        # deliberately exempt. Real stdio regressions protect both error paths.
+        ::MCP::Configuration.new(exception_reporter: ->(_exception, _context) {}, validate_tool_call_results: true)
+      end
+
+      def tools
+        handler = method(:respond)
+        DESCRIPTIONS.map do |operation, description|
+          ::MCP::Tool.define(
+            name: "abbu_#{operation}", description: description,
+            input_schema: operation == :query ? QUERY_SCHEMA : EMPTY_SCHEMA,
+            output_schema: output_schema(operation), annotations: ANNOTATIONS
+          ) do |**arguments|
+            handler.call(operation, arguments.except(:server_context))
+          end
+        end
+      end
+
+      def output_schema(operation)
+        { type: 'object', properties: { data: DATA_SCHEMAS.fetch(operation, ARRAY_DATA) },
+          required: ['data'], additionalProperties: false }
+      end
+
+      def respond(operation, arguments)
+        payload = { data: @session.public_send(operation, **arguments) }
+        response(payload)
+      rescue ArgumentError
+        response({ error: { code: 'invalid_query', message: 'Check mode, timestamp and pagination.' } }, error: true)
+      rescue StandardError
+        # Never echo exception messages that might include contact values or paths.
+        response({ error: { code: 'read_failed', message: 'Unable to read the configured input.' } }, error: true)
+      end
+
+      def response(payload, error: false)
+        ::MCP::Tool::Response.new([{ type: 'text', text: JSON.generate(payload) }],
+                                  structured_content: payload, error: error)
+      end
+    end
+  end
+end

data/lib/abbu/mcp.rb

@@ -0,0 +1,11 @@
+# lib/abbu/mcp.rb
+# frozen_string_literal: true
+
+# Optional SDK activation never runs from require 'abbu'.
+gem 'mcp', '~> 1.6.1'
+require 'json'
+require 'mcp'
+
+require_relative '../abbu'
+require_relative 'mcp/read_session'
+require_relative 'mcp/server'