pikuri-thunderbird 0.1.0

data/lib/pikuri/thunderbird/gloda/mail.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Thunderbird
+    class Gloda
+      # Mail search + read over the {Gloda} index service — the mail half of the
+      # corpus (its people counterpart is {Gloda::Contacts}).
+      #
+      #   mail = Gloda::Mail.new(gloda: gloda)
+      #   hit  = mail.search(query: 'invoice', limit: 10).first  # ranked, deduped
+      #   mail.read(message_id: hit[:message_id])                # full decoded body
+      #
+      # It owns no resources: it queries {Gloda}'s live snapshot through
+      # {Gloda#with_fresh_db} (so a rebuild under it is transparent), and there
+      # is nothing to close — the {Gloda} it holds is closed by its own owner.
+      #
+      # == Gmail dedup
+      #
+      # Gmail exposes each label as an IMAP folder, so a message with N labels
+      # yields N Gloda rows (+[Gmail]/All Mail+ alone duplicates nearly
+      # everything). {#search} over-fetches and dedups by +headerMessageID+
+      # (falling back to a +gloda:<id>+ handle when absent) *before* the top-N
+      # cap, so duplicates can't eat result slots.
+      class Mail
+        # @return [Integer] over-fetch multiple before dedup+cap (so Gmail
+        #   label duplicates don't shrink recall).
+        OVERFETCH = 4
+
+        # @return [Integer] absolute floor on the pre-dedup fetch.
+        MIN_FETCH = 40
+
+        # @param gloda [Gloda] the index service whose snapshot this queries.
+        # @return [Mail]
+        def initialize(gloda:)
+          @gloda = gloda
+        end
+
+        # Ranked, deduped mail search. +query+ is matched as an OR of terms
+        # over all decoded columns (recall-first); +bm25+ ranks, recency
+        # breaks ties. Structured filters are exact predicates applied
+        # alongside. An empty query degrades to a filter-only, date-ordered
+        # listing.
+        #
+        # @param query [String] free text over body/subject/author/recipients/
+        #   attachment-names.
+        # @param limit [Integer] max hits after dedup.
+        # @param from [String, nil] substring match on the author.
+        # @param to [String, nil] substring match on the recipients.
+        # @param subject [String, nil] substring match on the subject.
+        # @param after [Time, nil] only messages on/after this instant.
+        # @param before [Time, nil] only messages on/before this instant.
+        # @param folder [String, nil] exact Gloda folder name.
+        # @return [Array<Hash>] +[{message_id:, date: Time, from:, to:,
+        #   subject:, folder:, snippet:}, …]+, best first, deduped.
+        def search(query:, limit:, from: nil, to: nil, subject: nil,
+                   after: nil, before: nil, folder: nil)
+          fetch = [limit * OVERFETCH, MIN_FETCH].max
+          rows = @gloda.with_fresh_db do |db|
+            if query.to_s.strip.empty?
+              filter_only(db, from:, to:, subject:, after:, before:, folder:, fetch:)
+            else
+              fts_search(db, query:, from:, to:, subject:, after:, before:, folder:, fetch:)
+            end
+          end
+          dedup(rows).first(limit)
+        end
+
+        # Full decoded body + headers + attachment names for one message.
+        #
+        # @param message_id [String] the {#search} handle (an RFC +Message-ID+
+        #   or a +gloda:<id>+ fallback).
+        # @return [Hash, nil] +{message_id:, date:, from:, to:, subject:,
+        #   folder:, attachment_names:, body:}+, or +nil+ if not found.
+        def read(message_id:)
+          gloda_id = message_id.to_s[/\Agloda:(\d+)\z/, 1]
+          where, bind = gloda_id ? ['m.id = ?', gloda_id.to_i] : ['m.headerMessageID = ?', message_id]
+          row = @gloda.with_fresh_db do |db|
+            db.execute(<<~SQL, [bind]).first
+              SELECT m.id, m.headerMessageID, m.date,
+                     c.c0body, c.c1subject, c.c2attachmentNames, c.c3author, c.c4recipients,
+                     fl.name AS folder
+              FROM messages m
+              JOIN messagesText_content c ON c.docid = m.id
+              LEFT JOIN folderLocations fl ON fl.id = m.folderID
+              WHERE #{where} AND m.deleted = 0
+              ORDER BY m.date DESC
+              LIMIT 1
+            SQL
+          end
+          return nil unless row
+
+          id, header_msgid, date_us, body, subj, attach, author, recipients, folder = row
+          {
+            message_id: header_msgid && !header_msgid.empty? ? header_msgid : "gloda:#{id}",
+            date: to_time(date_us), from: author, to: recipients, subject: subj,
+            folder: folder, attachment_names: attach.to_s, body: body.to_s
+          }
+        end
+
+        private
+
+        # @return [Array<Array>] raw result rows (see {#row_to_hit} for shape).
+        def fts_search(db, query:, from:, to:, subject:, after:, before:, folder:, fetch:)
+          clauses = ['fts MATCH ?', 'm.deleted = 0']
+          binds = [match_expr(query)]
+          append_filters(clauses, binds, from:, to:, subject:, after:, before:, folder:)
+          db.execute(<<~SQL, binds + [fetch])
+            SELECT m.headerMessageID, m.id, m.date, c.c1subject, c.c3author, c.c4recipients,
+                   fl.name, snippet(fts, 0, '', '', ' … ', 12)
+            FROM fts
+            JOIN messages m ON m.id = fts.rowid
+            JOIN messagesText_content c ON c.docid = fts.rowid
+            LEFT JOIN folderLocations fl ON fl.id = m.folderID
+            WHERE #{clauses.join(' AND ')}
+            ORDER BY bm25(fts), m.date DESC
+            LIMIT ?
+          SQL
+        end
+
+        # @return [Array<Array>] raw result rows, date-ordered.
+        def filter_only(db, from:, to:, subject:, after:, before:, folder:, fetch:)
+          clauses = ['m.deleted = 0']
+          binds = []
+          append_filters(clauses, binds, from:, to:, subject:, after:, before:, folder:)
+          db.execute(<<~SQL, binds + [fetch])
+            SELECT m.headerMessageID, m.id, m.date, c.c1subject, c.c3author, c.c4recipients,
+                   fl.name, substr(c.c0body, 1, 180)
+            FROM messages m
+            JOIN messagesText_content c ON c.docid = m.id
+            LEFT JOIN folderLocations fl ON fl.id = m.folderID
+            WHERE #{clauses.join(' AND ')}
+            ORDER BY m.date DESC
+            LIMIT ?
+          SQL
+        end
+
+        # Append the shared structured predicates (mutates +clauses+/+binds+).
+        #
+        # @return [void]
+        def append_filters(clauses, binds, from:, to:, subject:, after:, before:, folder:)
+          add_like(clauses, binds, 'c.c3author', from)
+          add_like(clauses, binds, 'c.c4recipients', to)
+          add_like(clauses, binds, 'c.c1subject', subject)
+          if after
+            clauses << 'm.date >= ?'
+            binds << to_prtime(after)
+          end
+          if before
+            clauses << 'm.date <= ?'
+            binds << to_prtime(before)
+          end
+          if folder && !folder.empty?
+            clauses << 'fl.name = ?'
+            binds << folder
+          end
+        end
+
+        # @return [void]
+        def add_like(clauses, binds, column, needle)
+          return if needle.nil? || needle.to_s.empty?
+
+          clauses << "#{column} LIKE '%' || ? || '%'"
+          binds << needle.to_s
+        end
+
+        # Build the FTS5 MATCH expression: OR of the query's terms, each
+        # phrase-quoted (internal +"+ doubled) so FTS5 syntax in user input is
+        # inert. OR maximizes recall; bm25 does the ranking.
+        #
+        # @param query [String]
+        # @return [String]
+        def match_expr(query)
+          terms = query.to_s.scan(/[[:alnum:]]+/)
+          return '""' if terms.empty?
+
+          terms.map { |t| %("#{t.gsub('"', '""')}") }.join(' OR ')
+        end
+
+        # @param rows [Array<Array>] raw rows.
+        # @return [Array<Hash>] hit hashes, deduped by handle, order preserved.
+        def dedup(rows)
+          seen = {}
+          rows.each do |row|
+            hit = row_to_hit(row)
+            seen[hit[:message_id]] ||= hit
+          end
+          seen.values
+        end
+
+        # @param row [Array] +[headerMessageID, id, date_us, subject, author,
+        #   recipients, folder, snippet]+
+        # @return [Hash]
+        def row_to_hit(row)
+          header_msgid, id, date_us, subject, author, recipients, folder, snippet = row
+          {
+            message_id: header_msgid && !header_msgid.empty? ? header_msgid : "gloda:#{id}",
+            date: to_time(date_us), from: author, to: recipients,
+            subject: subject, folder: folder, snippet: snippet.to_s.strip
+          }
+        end
+
+        # @param prtime_us [Integer, nil] PRTime microseconds since epoch.
+        # @return [Time, nil]
+        def to_time(prtime_us)
+          return nil if prtime_us.nil? || prtime_us.zero?
+
+          Time.at(prtime_us / 1_000_000)
+        end
+
+        # @param time [Time]
+        # @return [Integer] PRTime microseconds.
+        def to_prtime(time) = (time.to_i * 1_000_000)
+      end
+    end
+  end
+end

data/lib/pikuri/thunderbird/gloda.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'sqlite3'
+
+module Pikuri
+  module Thunderbird
+    # Provides queryable access to Thunderbird's Gloda index
+    # (+global-messages-db.sqlite+) — a *pre-decoded corpus*: Gloda has already
+    # MIME-decoded, HTML-stripped, and split every message into body / subject /
+    # attachment-names / author / recipients, and keeps it fresh for free. This
+    # is the *service*: it snapshots the locked live file, builds an ephemeral
+    # FTS5 index into the copy, tracks freshness, and hands out a current
+    # connection — but runs no queries itself. Two views do the querying:
+    #
+    #   gloda = Gloda.new(gloda_path: profile.gloda_path, cache_dir: dir)
+    #   gloda.available?                       # is the Gloda file present?
+    #   Gloda::Mail.new(gloda: gloda)          # mail search + read
+    #   Gloda::Contacts.new(gloda: gloda)      # name → address + novelty
+    #   gloda.close                            # closes the snapshot connection
+    #
+    # A view queries through {#with_fresh_db}; it never caches the connection
+    # (a rebuild reopens it). pikuri never touches the locked live file — it
+    # works against a {DatabaseSnapshot} copy and builds its own FTS5 index into that
+    # copy (Gloda's own +messagesText+ is an fts3 vtable behind the custom
+    # +mozporter+ tokenizer, which the sqlite3 gem can't open).
+    #
+    # This service is *specific to Gloda's schema* — the FTS5 index it builds is
+    # over Gloda's decoded columns (+c0body+ … +c4recipients+), so it is not a
+    # generic SQLite handle and does not serve the calendar DBs ({Calendar} has
+    # its own {DatabaseSnapshot} + backend).
+    #
+    # == Freshness & consistency (one signal)
+    #
+    # Each {#with_fresh_db} first compares the live Gloda change counter against
+    # the generation the current copy+index were built from; if it moved, a
+    # fresh {DatabaseSnapshot} is taken and the FTS5 index rebuilt (~1 s). Between
+    # changes it's a 4-byte read and a no-op. The counter bumps on any Gloda
+    # write — including read/star/tag flips during triage — so a rebuild can
+    # fire mid-conversation (desirable: the views then see new mail). See
+    # {DatabaseSnapshot}.
+    #
+    # Holds no external state beyond its own snapshot + connection, but {#close}
+    # is required for orderly teardown.
+    #
+    # == Sharing
+    #
+    # +P_shared_locked+, and sharing beats one-per-agent: the snapshot copy and
+    # the ~1 s FTS5 rebuild are then paid once for the machine, not once each.
+    # Three contracts come with that:
+    #
+    # * The lock is held **across the caller's block**. Releasing it at the
+    #   +yield+ would hand out exactly the connection a rebuild then closes, so
+    #   a rebuild parks a second agent for ~1 s — the cost it would have paid
+    #   alone anyway; every other query is local SQLite.
+    # * A view may therefore never nest {#with_fresh_db} inside another (the
+    #   guard is a +Mutex+, not a +Monitor+).
+    # * {#close} needs no refcount: it drops the fd, and the next
+    #   {#with_fresh_db} reopens the same copy. A co-owner pays a rebuild,
+    #   never a failure.
+    #
+    # The +cache_dir+ is what must stay unshared — two instances over one
+    # snapshot path +cp -f+ under each other's open fd.
+    class Gloda
+      LOGGER = Pikuri.logger_for('Thunderbird::Gloda')
+
+      # @param gloda_path [String] path to +global-messages-db.sqlite+.
+      # @param cache_dir [String] private 0700 dir for the snapshot copy. Must
+      #   be this instance's alone — see the +== Sharing+ section.
+      # @return [Gloda]
+      def initialize(gloda_path:, cache_dir:)
+        @source = gloda_path
+        @snapshot = DatabaseSnapshot.new(source: gloda_path, dir: cache_dir)
+        @db = nil
+        @indexed_generation = nil
+        @lock = Mutex.new
+      end
+
+      # @return [Boolean] whether the Gloda index file exists (the mail /
+      #   contact tools' registration gate).
+      def available? = File.file?(@source)
+
+      # Yield the snapshot connection, guaranteed current — a stale index is
+      # rebuilt first. The sole seam the {Gloda::Mail} / {Gloda::Contacts} views
+      # query through; they never cache the returned connection, because a
+      # rebuild reopens it.
+      #
+      #   gloda.with_fresh_db { |db| db.execute('SELECT count(*) FROM messages') }
+      #
+      # The lock spans the block, so the yielded connection cannot be swapped
+      # mid-query and the block must not re-enter (see +== Sharing+).
+      #
+      # @yield [SQLite3::Database] the fresh snapshot connection.
+      # @return [Object] the block's value.
+      def with_fresh_db
+        @lock.synchronize do
+          ensure_fresh
+          yield @db
+        end
+      end
+
+      # Close the snapshot connection (the snapshot dir itself is
+      # finalizer-reaped). Idempotent, and safe while another agent shares this
+      # instance — the next {#with_fresh_db} reopens.
+      #
+      # @return [void]
+      def close
+        @lock.synchronize { close! }
+      end
+
+      private
+
+      # {#close} without the lock — the form the already-holding callers use;
+      # +Mutex+ is not reentrant.
+      #
+      # @return [void]
+      def close!
+        @db&.close
+        @db = nil
+      end
+
+      # (Re)take the snapshot + rebuild the FTS5 index iff the live Gloda
+      # generation differs from what the current index was built from. Callers
+      # hold the lock.
+      #
+      # @return [void]
+      def ensure_fresh
+        live = DatabaseSnapshot.change_counter(@source)
+        return if @db && @indexed_generation && live == @indexed_generation
+
+        close! # release the fd before cp overwrites the copy in place
+        @snapshot.refresh
+        open_and_index
+        @indexed_generation = @snapshot.generation
+      end
+
+      # Open the fresh snapshot copy read-write and build an external-content
+      # FTS5 index over Gloda's decoded columns (stores only the index, no
+      # second text copy; hits map back by rowid = +messages.id+).
+      #
+      # @return [void]
+      def open_and_index
+        @db = SQLite3::Database.new(@snapshot.path)
+        @db.execute(<<~SQL)
+          CREATE VIRTUAL TABLE IF NOT EXISTS fts USING fts5(
+            c0body, c1subject, c2attachmentNames, c3author, c4recipients,
+            content='messagesText_content', content_rowid='docid'
+          )
+        SQL
+        @db.execute("INSERT INTO fts(fts) VALUES('rebuild')")
+      end
+    end
+  end
+end

data/lib/pikuri/thunderbird/ical_line.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Thunderbird
+    # Parses the little iCalendar that Thunderbird leaves opaque — pikuri needs
+    # it only for +cal_attendees+, whose rows are raw +ATTENDEE+/+ORGANIZER+
+    # content lines (everything else is already in normalized columns). The
+    # inbound counterpart to {IcsEvent}'s outbound line *building*. Two entry
+    # points:
+    #
+    #   # domain: an attendee line → a typed {Attendee}
+    #   who = IcalLine.attendee('ATTENDEE;CN="Last, First";PARTSTAT=ACCEPTED:mailto:x@y.com')
+    #   who.name        # => "Last, First"
+    #   who.email       # => "x@y.com"
+    #   who.optional?   # => false
+    #
+    #   # generic: any content line → its name/params/value
+    #   line = IcalLine.parse('ATTENDEE;PARTSTAT=ACCEPTED:mailto:x@y.com')
+    #   line.params["PARTSTAT"]   # => "ACCEPTED"
+    #
+    # Both are quote-aware — a +;+/+:+ inside a double-quoted param value
+    # doesn't split — and upcase param names (RFC 5545 §3.2: case-insensitive).
+    # +TEXT+-value backslash *unescaping* is deliberately not done: the names
+    # and addresses +cal_attendees+ carries arrive quoted, not +\,+/+\;+-escaped,
+    # so it would be dead code.
+    #
+    # Immutable.
+    module IcalLine
+      # One attendee or organizer, parsed from an +ATTENDEE+/+ORGANIZER+ line.
+      # +email+ falls back from the +EMAIL+ param to the +mailto:+ value,
+      # +name+ from +CN+ to the email — so both are always present.
+      #
+      # @!attribute [r] name
+      #   @return [String] display name (+CN+), or the email when there's no CN.
+      # @!attribute [r] email
+      #   @return [String] the address, sans +mailto:+.
+      # @!attribute [r] status
+      #   @return [String, nil] raw +PARTSTAT+ (+"ACCEPTED"+, +"NEEDS-ACTION"+…).
+      # @!attribute [r] role
+      #   @return [String, nil] raw +ROLE+ (+"REQ-PARTICIPANT"+, +"OPT-PARTICIPANT"+).
+      # @!attribute [r] cutype
+      #   @return [String, nil] raw +CUTYPE+ (+"INDIVIDUAL"+, +"RESOURCE"+…).
+      # @!attribute [r] organizer
+      #   @return [Boolean] whether the line was an +ORGANIZER+, not an +ATTENDEE+.
+      Attendee = Data.define(:name, :email, :status, :role, :cutype, :organizer) do
+        # @return [Boolean] the ORGANIZER (vs a plain attendee).
+        def organizer? = organizer
+
+        # @return [Boolean] an optional invitee (+ROLE=OPT-PARTICIPANT+).
+        def optional? = role == 'OPT-PARTICIPANT'
+
+        # @return [Boolean] a room/equipment, not a person (+CUTYPE=RESOURCE+).
+        def resource? = cutype == 'RESOURCE'
+      end
+
+      # One generic parsed content line.
+      #
+      # @!attribute [r] name
+      #   @return [String] the property name, upcased (e.g. +"ATTENDEE"+).
+      # @!attribute [r] params
+      #   @return [Hash{String => String}] param name (upcased) → unquoted value.
+      # @!attribute [r] value
+      #   @return [String] the text after the first unquoted +:+ (+""+ if none).
+      Parsed = Data.define(:name, :params, :value)
+
+      # Parse one +ATTENDEE+/+ORGANIZER+ content line into an {Attendee}.
+      #
+      # @param line [String] one raw +cal_attendees.icalString+.
+      # @return [Attendee]
+      def self.attendee(line)
+        parsed = parse(line)
+        email = (parsed.params['EMAIL'].to_s.empty? ? parsed.value.sub(/\Amailto:/i, '') : parsed.params['EMAIL']).strip
+        name = parsed.params['CN'].to_s.strip
+        Attendee.new(
+          name: name.empty? ? email : name, email: email,
+          status: parsed.params['PARTSTAT'], role: parsed.params['ROLE'],
+          cutype: parsed.params['CUTYPE'], organizer: parsed.name == 'ORGANIZER'
+        )
+      end
+
+      # Parse one content line into its {Parsed} parts. Never raises — a line
+      # with no +:+ yields an empty value, a token with no +=+ is skipped.
+      #
+      # @param line [String] a raw iCal content line.
+      # @return [Parsed]
+      def self.parse(line)
+        head, value = split_unquoted(line, ':', max: 2)
+        name, *param_tokens = split_unquoted(head, ';')
+        params = param_tokens.each_with_object({}) do |token, h|
+          key, val = token.split('=', 2)
+          h[key.to_s.upcase] = unquote(val) if val
+        end
+        Parsed.new(name: name.to_s.upcase, params: params, value: value.to_s)
+      end
+
+      # Split +str+ on the single char +delim+, ignoring delimiters inside a
+      # double-quoted iCal param value; +max+ caps the part count (like
+      # +String#split+'s limit) so a value's own +mailto:+ colon survives.
+      #
+      # @param str [String]
+      # @param delim [String] one-character delimiter.
+      # @param max [Integer, nil] max parts, or +nil+ for unlimited.
+      # @return [Array<String>]
+      def self.split_unquoted(str, delim, max: nil)
+        parts = []
+        buf = +''
+        in_quote = false
+        str.to_s.each_char do |c|
+          if c == '"'
+            in_quote = !in_quote
+            buf << c
+          elsif c == delim && !in_quote && (max.nil? || parts.size < max - 1)
+            parts << buf
+            buf = +''
+          else
+            buf << c
+          end
+        end
+        parts << buf
+        parts
+      end
+      private_class_method :split_unquoted
+
+      # @param str [String, nil]
+      # @return [String] +str+ with one layer of surrounding double quotes off.
+      def self.unquote(str) = str.to_s.gsub(/\A"|"\z/, '')
+      private_class_method :unquote
+    end
+  end
+end

data/lib/pikuri/thunderbird/ics_event.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module Pikuri
+  module Thunderbird
+    # Builds the iCalendar (+.ics+) text that {CalendarCreate} stages for
+    # Thunderbird's import wizard. The text *is* the injection surface — the same
+    # role {MailtoUri} plays for compose — because a raw newline in a text field
+    # would let an attacker-authored description close +DESCRIPTION+ and inject
+    # its own +ATTENDEE+ line or a second +VEVENT+. So every text value is
+    # RFC-5545-escaped (+\+, +;+, +,+, newline) and control bytes are stripped
+    # before it joins a property line:
+    #
+    #   IcsEvent.build(title: 'Q2 review', start: Time.parse('2026-07-20 14:00'))
+    #   # BEGIN:VCALENDAR … BEGIN:VEVENT
+    #   #   SUMMARY:Q2 review
+    #   #   DTSTART:20260720T120000Z      ← host-local 14:00 emitted as UTC
+    #   #   DTEND:20260720T130000Z        ← default +1h
+    #   # END:VEVENT END:VCALENDAR
+    #
+    # == Time & all-day encoding
+    #
+    # Timed events emit +DTSTART+/+DTEND+ as UTC (+…Z+): the caller's {Time} is
+    # taken at face value and converted with +#utc+, so a bare "2pm" the user
+    # typed is 2pm in the *host* zone — the same "host zone == user zone"
+    # heuristic {Calendar}/{DateHelpers} already read events back with. An
+    # explicit offset in the input (e.g. "15:00 +0900") is honored too —
+    # {DateHelpers.parse_time} keeps it and +#utc+ maps it to the right instant,
+    # so +start+ and +finish+ may legitimately sit in different zones. All-day events
+    # emit +VALUE=DATE+ with an iCal *exclusive* +DTEND+ (a single-day event's
+    # DTEND is the next day), so +finish+ is the user-intuitive *last* day.
+    #
+    # Immutable.
+    module IcsEvent
+      # @return [String] product id line value; identifies pikuri as the writer.
+      PRODID = '-//pikuri//thunderbird//EN'
+
+      # C0/C1 control bytes (except the ones {.escape} turns into +\n+) — invalid
+      # in an ICS value and a structure-injection vector; stripped outright.
+      #
+      # A +String#delete+ byte set, not a regexp: {.escape} strips these from the
+      # *binary* copy of the value, keeping the strip byte-wise (every byte here
+      # is ASCII, so it can never bite into a multibyte sequence) without a
+      # +/n+-flagged regexp meeting a UTF-8 string. Ruby warns on that pairing
+      # ("historical binary regexp match"), and an interpreter warning goes to the
+      # raw +$stderr+, bypassing +Pikuri.log_io+ and painting over a TUI's screen
+      # — one accented character in a title was enough. Dropping the +/n+ instead
+      # would have made the strip character-wise and raise +ArgumentError+ on
+      # invalid UTF-8, which {CalendarCreate} then reports as a bad date.
+      #
+      # @return [String] a +String#delete+ character set.
+      CONTROL = "\x00-\x08\x0b\x0c\x0e-\x1f\x7f"
+
+      # Build the +.ics+ document for one event.
+      #
+      # @param title [String] event summary (SUMMARY).
+      # @param start [Time] start instant (timed) or day (all-day, date part used).
+      # @param finish [Time, nil] end instant / last all-day date; +nil+ defaults
+      #   to +start + 1h+ (timed) or the same single day (all-day).
+      # @param all_day [Boolean] emit +VALUE=DATE+ instead of a UTC datetime.
+      # @param location [String, nil] LOCATION, or +nil+ to omit.
+      # @param description [String, nil] DESCRIPTION, or +nil+ to omit.
+      # @param uid [String] event UID; defaults to a fresh random one.
+      # @param dtstamp [Time] the DTSTAMP instant; defaults to now.
+      # @return [String] a complete +VCALENDAR+ with one +VEVENT+, CRLF-joined.
+      def self.build(title:, start:, finish: nil, all_day: false, location: nil, description: nil,
+                     uid: "#{SecureRandom.uuid}@pikuri", dtstamp: Time.now)
+        lines = [
+          'BEGIN:VCALENDAR', 'VERSION:2.0', "PRODID:#{PRODID}", 'METHOD:PUBLISH',
+          'BEGIN:VEVENT', "UID:#{escape(uid)}", "DTSTAMP:#{utc_stamp(dtstamp)}",
+          *date_lines(start, finish, all_day),
+          "SUMMARY:#{escape(title)}"
+        ]
+        lines << "LOCATION:#{escape(location)}" if present?(location)
+        lines << "DESCRIPTION:#{escape(description)}" if present?(description)
+        lines += %w[END:VEVENT END:VCALENDAR]
+        # CRLF line endings + a trailing CRLF, per RFC 5545 §3.1.
+        "#{lines.join("\r\n")}\r\n"
+      end
+
+      # @return [Array<String>] the DTSTART/DTEND property lines.
+      def self.date_lines(start, finish, all_day)
+        return timed_lines(start, finish) unless all_day
+
+        last = finish || start
+        ["DTSTART;VALUE=DATE:#{date_stamp(start)}",
+         "DTEND;VALUE=DATE:#{date_stamp(last + 86_400)}"] # exclusive: last day + 1
+      end
+      private_class_method :date_lines
+
+      # @return [Array<String>]
+      def self.timed_lines(start, finish)
+        ["DTSTART:#{utc_stamp(start)}", "DTEND:#{utc_stamp(finish || start + 3600)}"]
+      end
+      private_class_method :timed_lines
+
+      # @param time [Time]
+      # @return [String] +"YYYYMMDDTHHMMSSZ"+ (UTC).
+      def self.utc_stamp(time) = time.getutc.strftime('%Y%m%dT%H%M%SZ')
+      private_class_method :utc_stamp
+
+      # @param time [Time]
+      # @return [String] +"YYYYMMDD"+ (local date, for all-day VALUE=DATE).
+      def self.date_stamp(time) = time.getlocal.strftime('%Y%m%d')
+      private_class_method :date_stamp
+
+      # RFC 5545 §3.3.11 TEXT escaping + control-byte strip (the injection
+      # defense). Long lines are left unfolded — Thunderbird reads them fine.
+      #
+      # @param value [String]
+      # @return [String]
+      def self.escape(value)
+        # Block form: the returned strings are used literally, sidestepping
+        # gsub's backreference interpretation of a replacement String. Backslash
+        # first, so the escapes introduced below aren't themselves re-escaped.
+        value.to_s.b.delete(CONTROL).force_encoding(Encoding::UTF_8)
+             .gsub('\\') { '\\\\' }
+             .gsub(';') { '\\;' }
+             .gsub(',') { '\\,' }
+             .gsub(/\r\n|\r|\n/) { '\\n' }
+      end
+      private_class_method :escape
+
+      # @return [Boolean]
+      def self.present?(value) = !value.nil? && !value.to_s.strip.empty?
+      private_class_method :present?
+    end
+  end
+end