portage-cli 0.9.0 → 0.11.0

data/lib/portage/cli/doctor.rb

@@ -42,7 +42,8 @@ module Portage
       #   those four warnings were noise on every fresh install.
       def initialize(adapter_class: nil, proxy_settings: ProxySettings.new, install_doctor: InstallDoctor.new,
                      seller: true, dot_env_path: DotEnv.loaded_path, index_stores: Index::Store.new,
-                     index_products: Index::ProductStore.new, known_cache: Index::KnownCache.new)
+                     index_products: Index::ProductStore.new, known_cache: Index::KnownCache.new,
+                     index_database: Index::Database.new(path: Index::Database.path_for(Index::Store::PATH)))
         @adapter_class = adapter_class
         @proxy_settings = proxy_settings
         @install_doctor = install_doctor
@@ -51,6 +52,7 @@ module Portage
         @index_stores = index_stores
         @index_products = index_products
         @known_cache = known_cache
+        @index_database = index_database
       end
 
       # `portage setup` always offers its wizard on a TTY; a bare `portage
@@ -210,12 +212,20 @@ module Portage
       # leaves behind.
       def index_finding
         refresh_known_cache_if_stale
-        return Finding.new(check: "index", level: "info", message: "#{index_message}\n#{known_cache_message}") \
-          if @index_stores.exists?
+        first = @index_stores.exists? ? index_message : no_index_message
+        database = @index_database.info
+        Finding.new(check: "index", level: "info", details: { database: database },
+                    message: [first, database_message(database), known_cache_message].join("\n"))
+      end
+
+      def no_index_message
+        "No local index yet — run `portage index build` to give `find` a list of " \
+          "stores/products on top of stores.yml and web search."
+      end
 
-        Finding.new(check: "index", level: "info",
-                    message: "No local index yet — run `portage index build` to give `find` a list of " \
-                             "stores/products on top of stores.yml and web search.\n#{known_cache_message}")
+      def database_message(info)
+        "Index database: #{info[:path]} (#{info[:stores]} store row(s), #{info[:products]} product row(s), " \
+          "FTS5 #{info[:fts5] ? 'available' : 'not available'})."
       end
 
       def refresh_known_cache_if_stale

data/lib/portage/cli/find.rb

@@ -229,9 +229,11 @@ module Portage
         amount, currency = price_of(product)
         return nil if over_max_price?(amount)
 
-        { store: store[:origin], source: store[:source], checkout: store[:checkout],
-          product_id: field(product, "id"), title: field(product, "title"),
-          amount: amount, currency: currency, url: field(product, "url") }
+        OfferSources.with_product(
+          { store: store[:origin], source: store[:source], checkout: store[:checkout],
+            product_id: field(product, "id"), title: field(product, "title"),
+            amount: amount, currency: currency, url: field(product, "url") }, product
+        )
       end
 
       # An unpriced offer stays in: no price isn't the same as too dear.

data/lib/portage/cli/handoff_host.rb

@@ -0,0 +1,33 @@
+require_relative "handoff_only"
+require_relative "offer_sources"
+
+module Portage
+  module Cli
+    # The one answer to "is this host hand-off only?" that both `buy` and
+    # `check` give, so `portage check` never says something `portage buy`
+    # wouldn't do. Three sources, in the order Buy has always consulted them:
+    # the user's own list (HandoffOnly, Amazon by default), the built-in
+    # retail hand-off hosts (Walmart, eBay, Best Buy), and Etsy for an
+    # ordinary buyer — portage-ucp-etsy is a seller-side adapter, so a shop
+    # owner with their own ETSY_* credentials set is not hand-off only.
+    module HandoffHost
+      def self.restricted?(host, handoff_only: HandoffOnly.new)
+        return true if handoff_only.host?(host)
+        return true if OfferSources.retail_handoff_host?(host)
+
+        etsy_buyer_host?(host)
+      end
+
+      def self.etsy_buyer_host?(host)
+        HandoffOnly.matches_any?(host, %w[etsy.com]) && !etsy_adapter_configured?
+      end
+
+      def self.etsy_adapter_configured?
+        platform = Portage::Ucp::Resolver::PLATFORMS.find { |p| p.name == "Etsy" }
+        return false unless platform
+
+        Portage::Ucp::Resolver.missing_env(platform, Portage::Ucp::Resolver.env_for(platform)).empty?
+      end
+    end
+  end
+end

data/lib/portage/cli/index/builder.rb

@@ -37,6 +37,9 @@ module Portage
         THROTTLE = 0.1
         STALE_AFTER = 7 * 24 * 60 * 60
         TOP_CATEGORIES = 5
+        # Product sightings per ProductStore#upsert_many transaction — one
+        # products.json page's worth (docs/plans/local-catalogue.md Phase 2).
+        WRITE_BATCH = 250
 
         # Public so BrowserImport::Importer (Phase 3) labels a probed
         # origin's capabilities exactly the way an index build does.
@@ -94,13 +97,19 @@ module Portage
         # HandoffOnly) is recorded without ever probing it — the user
         # explicitly named it, but that's still not a request this process
         # sends.
-        def add(url)
+        #
+        # `crawl: true` (`index add URL --crawl`) then reads the store's own
+        # catalogue through Sources::StorefrontProducts into the index.
+        # Opt-in: a crawl is up to 21 more requests and 20s of pauses, where
+        # a plain add is one probe.
+        def add(url, crawl: false)
           origin = origin_of(url)
           return { added: false, message: "Not a valid http(s) URL: #{url}" } unless origin
           return store_manual_handoff_only(origin) if handoff_only_origin?(origin)
 
           session = probe(origin)
-          store_manual(origin, session)
+          result = store_manual(origin, session)
+          crawl ? crawl_added(origin, result) : result
         end
 
         # `portage index remove HOST`
@@ -184,10 +193,29 @@ module Portage
           { added: true, origin: origin, message: "Added #{origin} — hand-off only, never probed." }
         end
 
+        # `store_fields:` on a sighting (StorefrontProducts' crawl note and
+        # platform) lands on the store row as-is.
         def update_existing(origin, group)
           existing = @stores.find(origin)
+          fields = group.filter_map { |g| g[:store_fields] }.reduce({}, :merge)
           @stores.upsert(origin, sources: merged_sources(existing, group),
-                                 categories: merge_categories(existing["categories"], group))
+                                 categories: merge_categories(existing["categories"], group), **fields)
+        end
+
+        def crawl_added(origin, result)
+          sightings = Sources::StorefrontProducts.new(stores: @stores, handoff_only: @handoff_only)
+                                                 .crawl(origin, platform: @stores.find(origin)&.dig("platform"))
+          tagged = sightings.map { |s| s.merge(source: "storefront_products") }
+          apply(tagged, dry_run: false)
+          note = tagged.last.dig(:store_fields, :crawl)
+          result.merge(crawl: note, message: "#{result[:message]} #{crawl_message(note)}")
+        end
+
+        def crawl_message(note)
+          return "Catalogue not crawled (#{note['reason']})." if note["status"] == "skipped"
+
+          "Crawled #{note['products']} product(s) from #{note['pages']} page(s)" \
+            "#{" (stopped: #{note['reason']})" if note['reason']}."
         end
 
         def store_new(origin, session, group)
@@ -220,7 +248,7 @@ module Portage
           group.each do |sighting|
             next unless sighting[:title]
 
-            Classifier.categories_for(sighting[:title]).each { |id| tally[id] += 1 }
+            categories_of(sighting).each { |id| tally[id] += 1 }
           end
           tally.sort_by { |_id, weight| -weight }.first(TOP_CATEGORIES).to_h
         end
@@ -232,17 +260,26 @@ module Portage
         def capabilities_of(session) = self.class.capabilities_of(session)
 
         def store_products(sightings)
-          eligible = sightings.select { |s| s[:title] && @stores.find(s[:origin]) }
-          eligible.each { |sighting| store_product(sighting) }
+          known = Hash.new { |memo, origin| memo[origin] = !@stores.find(origin).nil? }
+          eligible = sightings.select { |s| s[:title] && known[s[:origin]] }
+          eligible.each_slice(WRITE_BATCH) { |batch| @products.upsert_many(batch.map { |s| product_row(s) }) }
           eligible.length
         end
 
-        def store_product(sighting)
-          key = product_key(sighting)
-          category = Classifier.categories_for(sighting[:title]).first
-          @products.upsert(key, origin: sighting[:origin], seen_at: @now.to_i, title: sighting[:title],
-                                brand: sighting[:brand], gtin: sighting[:gtin], category: category,
-                                sources: [sighting[:source]].compact)
+        # `product:` on a sighting (StorefrontProducts' handle, url,
+        # image_url, options, variant_ids) is stored alongside the usual
+        # fields.
+        def product_row(sighting)
+          { key: product_key(sighting), origin: sighting[:origin], seen_at: @now.to_i, title: sighting[:title],
+            brand: sighting[:brand], gtin: sighting[:gtin], category: categories_of(sighting).first,
+            sources: [sighting[:source]].compact, **sighting.fetch(:product, {}) }
+        end
+
+        # A source that already classified its sighting (StorefrontProducts,
+        # on product_type and tags) says so in `categories:`; otherwise the
+        # title is classified here.
+        def categories_of(sighting)
+          sighting[:categories] || Classifier.categories_for(sighting[:title])
         end
 
         # GTIN when a source has one (none do yet); otherwise a normalized

data/lib/portage/cli/index/database.rb

@@ -0,0 +1,150 @@
+require "json"
+require "fileutils"
+require "sqlite3"
+require_relative "schema"
+require_relative "legacy_import"
+
+module Portage
+  module Cli
+    module Index
+      # `~/.portage/index/index.sqlite3` — the one file behind Index::Store
+      # and Index::ProductStore (docs/plans/local-catalogue.md Phase 1).
+      # Plain SQL over the `sqlite3` gem, no ORM: every entry is stored as
+      # the same JSON object the old stores.json/products.json held, so the
+      # entry shapes documented on Store/ProductStore did not change.
+      #
+      # Posture: the file is created 0600 (and so are SQLite's -wal/-shm
+      # side files, which copy the main file's mode); it runs in WAL mode
+      # with a busy timeout; a failed write raises rather than being
+      # swallowed. Nothing is created until something is written — a read
+      # of an index that doesn't exist yet just comes back empty.
+      #
+      # Forward-only schema: MIGRATIONS[n] takes user_version n to n + 1,
+      # and a database stamped newer than this build knows is refused
+      # rather than guessed at.
+      #
+      # The open that creates the database also imports a legacy stores.json/
+      # products.json that sits beside it, in one transaction, then renames
+      # it to *.json.migrated. Only that one open does — later opens never
+      # look, even if the tables have since been emptied — and nothing is
+      # ever deleted.
+      class Database
+        class Error < StandardError; end
+
+        FILENAME = "index.sqlite3".freeze
+        BUSY_TIMEOUT_MS = 5_000
+
+        # table => its key column. The legacy json file for a table is
+        # "<table>.json".
+        TABLES = { "stores" => "origin", "products" => "key" }.freeze
+
+        # The database that lives beside a legacy stores.json/products.json.
+        def self.path_for(json_path) = File.join(File.dirname(json_path), FILENAME)
+
+        attr_reader :path
+
+        def initialize(path:)
+          @path = path
+        end
+
+        # True once there is something to read: the database itself, or a
+        # legacy json file that the next open will import.
+        def exists? = File.exist?(@path) || LegacyImport.files(File.dirname(@path)).any?
+
+        # @return [Hash] key => parsed entry, in insertion order.
+        def entries(table)
+          return {} unless exists?
+
+          execute("SELECT #{TABLES.fetch(table)}, data FROM #{table} ORDER BY rowid").to_h { |k, d| [k, JSON.parse(d)] }
+        end
+
+        def get(table, key)
+          return nil unless exists?
+
+          row = execute("SELECT data FROM #{table} WHERE #{TABLES.fetch(table)} = ?", [key]).first
+          row && JSON.parse(row.first)
+        end
+
+        def put(table, key, entry)
+          column = TABLES.fetch(table)
+          execute("INSERT INTO #{table} (#{column}, data) VALUES (?, ?) " \
+                  "ON CONFLICT(#{column}) DO UPDATE SET data = excluded.data", [key, JSON.generate(entry)])
+        end
+
+        def delete(table, key)
+          execute("DELETE FROM #{table} WHERE #{TABLES.fetch(table)} = ?", [key])
+        end
+
+        def count(table)
+          return 0 unless exists?
+
+          execute("SELECT COUNT(*) FROM #{table}").first.first
+        end
+
+        # Reentrant: a nested call joins the outer transaction. IMMEDIATE
+        # takes the write lock up front, so a read-modify-write inside it
+        # can't interleave with another process's.
+        def transaction(&)
+          return yield if connection.transaction_active?
+
+          connection.transaction(:immediate, &)
+        end
+
+        # @return [Array<Array>] raw rows — for the specs and Phase 2's
+        #   search; everything else goes through the entry methods above.
+        def execute(sql, binds = [])
+          connection.execute(sql, binds)
+        end
+
+        def pragma(name) = execute("PRAGMA #{name}").flatten.first
+
+        # What `portage doctor` reports.
+        def info
+          stores = count("stores")
+          products = count("products")
+          { path: @path, exists: File.exist?(@path), stores: stores, products: products,
+            fts5: Schema.fts5_available? }
+        end
+
+        private
+
+        def connection
+          @connection ||= open_connection
+        end
+
+        def open_connection
+          FileUtils.mkdir_p(File.dirname(@path))
+          File.open(@path, File::CREAT | File::WRONLY, 0o600) { nil }
+          FileUtils.chmod(0o600, @path)
+          db = SQLite3::Database.new(@path)
+          db.busy_timeout = BUSY_TIMEOUT_MS
+          db.execute("PRAGMA journal_mode = WAL")
+          db.execute("PRAGMA synchronous = NORMAL")
+          @connection = db
+          # One transaction, so a failed import leaves the database unstamped
+          # and the next open tries again rather than skipping the import.
+          transaction { LegacyImport.new(self, File.dirname(@path)).call if migrate.zero? }
+          db
+        rescue StandardError
+          @connection&.close
+          @connection = nil
+          raise
+        end
+
+        def migrate
+          version = @connection.get_first_value("PRAGMA user_version")
+          if version > Schema::MIGRATIONS.length
+            raise Error,
+                  "#{@path} is schema v#{version}, newer than this portage understands"
+          end
+
+          Schema::MIGRATIONS.drop(version).each_with_index do |step, i|
+            step.call(@connection)
+            @connection.execute("PRAGMA user_version = #{version + i + 1}")
+          end
+          version
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/index/entry_product.rb

@@ -0,0 +1,37 @@
+require "portage/ucp"
+
+module Portage
+  module Cli
+    module Index
+      # A ProductStore entry as the persisted subset of a UCP Product wire
+      # hash (docs/plans/local-catalogue.md Phase 3), for `index search`'s
+      # `product` field. Built only from what the index keeps, so it has no
+      # id, description, price_range or availability: the index never stores
+      # a price or stock, and a missing field is left out rather than faked.
+      # The live Product comes from `find`.
+      module EntryProduct
+        TAXONOMY = "google_product_category".freeze
+
+        module_function
+
+        # @param entry [Hash] a ProductStore entry.
+        # @return [Hash] string-keyed, UCP Product shaped.
+        def wire(entry)
+          wire = { "title" => entry["title"], "handle" => entry["handle"], "url" => entry["url"],
+                   "media" => media(entry["image_url"]), "options" => entry["options"],
+                   "variants" => Array(entry["variant_ids"]).map { |id| { "id" => id } },
+                   "categories" => category(entry["category"]) }
+          wire.reject { |_field, value| value.nil? || value == [] }
+        end
+
+        def media(url)
+          url.to_s.empty? ? nil : [Portage::Ucp::Media.new(type: "image", url: url).to_wire_h]
+        end
+
+        def category(id)
+          id.to_s.empty? ? nil : [Portage::Ucp::Category.new(value: id, taxonomy: TAXONOMY).to_wire_h]
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/index/legacy_import.rb

@@ -0,0 +1,54 @@
+require "json"
+
+module Portage
+  module Cli
+    module Index
+      # Moves a pre-SQLite stores.json/products.json into an Index::Database
+      # (docs/plans/local-catalogue.md Phase 1): every object entry, in one
+      # transaction, then the file is renamed to *.json.migrated. Nothing
+      # is ever deleted, and an unreadable or non-object file is left
+      # untouched. Index::Database runs this only on the open that creates
+      # the database, so it happens at most once.
+      class LegacyImport
+        # @return [Array<String>] the legacy json files present in `dir`.
+        def self.files(dir)
+          Database::TABLES.keys.map { |table| File.join(dir, "#{table}.json") }.select { |file| File.file?(file) }
+        end
+
+        def initialize(database, dir)
+          @database = database
+          @dir = dir
+        end
+
+        def call
+          self.class.files(@dir).each do |file|
+            entries = read(file)
+            next unless entries
+
+            @database.transaction do
+              entries.each { |key, entry| @database.put(File.basename(file, ".json"), key, entry) if entry.is_a?(Hash) }
+            end
+            rename(file)
+          end
+        end
+
+        private
+
+        def read(file)
+          parsed = JSON.parse(File.read(file, encoding: "UTF-8"))
+          parsed.is_a?(Hash) ? parsed : nil
+        rescue JSON::ParserError, SystemCallError
+          nil
+        end
+
+        # The rows are already committed, so a rename that fails must not
+        # fail the open — the file is just left where it was.
+        def rename(file)
+          File.rename(file, "#{file}.migrated")
+        rescue SystemCallError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/index/product_store.rb

@@ -1,10 +1,12 @@
 require "json"
-require "fileutils"
+require_relative "database"
+require_relative "search"
 
 module Portage
   module Cli
     module Index
-      # `~/.portage/index/products.json` — product identities the index has
+      # The `products` table of `~/.portage/index/index.sqlite3` (Index::Database;
+      # `products.json` before docs/plans/local-catalogue.md Phase 1) — product identities the index has
       # seen, one entry per GTIN/MPN (when a source gives one) or per
       # title+brand otherwise. **No prices or stock** — those are always
       # live, read straight from the store's own catalog at buy time
@@ -19,33 +21,92 @@ module Portage
       class ProductStore
         PATH = File.join(Dir.home, ".portage", "index", "products.json").freeze
 
+        # @param path [String] where the legacy products.json lives (or
+        #   would live) — the database sits beside it, and a products.json
+        #   found there is imported on first open.
         def initialize(path: PATH)
-          @path = path
+          @db = Database.new(path: Database.path_for(path))
         end
 
-        def all = entries.values
+        def all = @db.entries("products").values
 
-        def find(key) = entries[key]
+        def find(key) = @db.get("products", key)
 
         # @param key [String] a stable key for this product — the source's
         #   GTIN/MPN when it has one, else a normalized title+brand.
         # @param origin [String] the store this sighting came from.
         # @param seen_at [Integer] unix seconds.
         def upsert(key, origin:, seen_at:, **fields)
-          existing = entries[key] || { "key" => key, "aliases" => [], "stores" => [] }
+          @db.transaction { merge_and_write(key, origin, seen_at, fields) }
+        end
+
+        # A batch of sightings in one transaction — all of them land or,
+        # if any raises, none do. Each row is a Hash: `key:`, `origin:`,
+        # `seen_at:` plus the same fields #upsert takes. Rows merge in
+        # order, so a key repeated in one batch accumulates like two
+        # #upsert calls would.
+        # @return [Array<Hash>] the merged entries, in row order.
+        def upsert_many(rows)
+          return [] if rows.empty?
+
+          @db.transaction do
+            rows.map do |row|
+              fields = row.except(:key, :origin, :seen_at)
+              merge_and_write(row.fetch(:key), row.fetch(:origin), row.fetch(:seen_at), fields)
+            end
+          end
+        end
+
+        def exists? = @db.exists?
+
+        def count = @db.count("products")
+
+        # `index show --products`: one page of entries, in insertion order.
+        def page(number, per_page:)
+          return [] unless exists?
+
+          offset = ([number.to_i, 1].max - 1) * per_page
+          rows = @db.execute("SELECT data FROM products ORDER BY id LIMIT ? OFFSET ?", [per_page, offset])
+          rows.map { |(data)| JSON.parse(data) }
+        end
+
+        # `portage index search` (docs/plans/local-catalogue.md Phase 2):
+        # every query word must match title, brand, category or an alias
+        # (as a prefix, after dropping a plural ending), best bm25 first.
+        # Without FTS5 (a system SQLite built without it) the same filters
+        # run as a LIKE scan, unranked. Untrusted seeds, same as every
+        # other entry: no price, no stock.
+        # @param store [String, nil] a host or URL; matches that host's origin.
+        # @return [Array<Hash>] entries.
+        def search(query, category: nil, store: nil, limit: 20)
+          words = Search.words(query)
+          return [] if words.empty? || !exists?
+
+          sql, binds = Search.sql(words, category: category, host: Search.host_of(store), limit: limit,
+                                         fts: search_engine == "fts5")
+          @db.execute(sql, binds).map { |(data)| JSON.parse(data) }
+        end
+
+        # "fts5", or "like" when the database has no products_fts table.
+        def search_engine
+          return Schema.fts5_available? ? "fts5" : "like" unless exists?
+
+          fts = @db.execute("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'products_fts'")
+          fts.empty? ? "like" : "fts5"
+        end
+
+        private
+
+        def merge_and_write(key, origin, seen_at, fields)
+          existing = @db.get("products", key) || { "key" => key, "aliases" => [], "stores" => [] }
           aliases = merge_aliases(existing, fields[:title])
           merged = existing.merge(fields.transform_keys(&:to_s)) { |field, old, new| merge_field(field, old, new) }
           merged["aliases"] = aliases
           merged["stores"] = merge_stores(merged["stores"], origin, seen_at)
-          entries[key] = merged
-          write
+          @db.put("products", key, merged)
           merged
         end
 
-        def exists? = File.exist?(@path)
-
-        private
-
         # `aliases`/`stores` accumulate across upserts (merged separately
         # below), `sources` is the union of every sighting's; every other
         # field (title, brand, gtin, category) is just the latest
@@ -72,29 +133,6 @@ module Portage
           kept = Array(stores).reject { |s| s["origin"] == origin }
           (kept + [{ "origin" => origin, "last_seen" => seen_at }]).sort_by { |s| s["origin"] }
         end
-
-        def entries
-          @entries ||= read
-        end
-
-        def read
-          return {} unless File.readable?(@path)
-
-          # See Index::Store#read's comment — a product title routinely
-          # carries non-ASCII bytes, so this has to read as UTF-8 rather
-          # than whatever the process's default external encoding is.
-          parsed = JSON.parse(File.read(@path, encoding: "UTF-8"))
-          parsed.is_a?(Hash) ? parsed : {}
-        rescue StandardError
-          {}
-        end
-
-        def write
-          FileUtils.mkdir_p(File.dirname(@path))
-          File.write(@path, JSON.generate(@entries))
-        rescue StandardError
-          nil
-        end
       end
     end
   end

data/lib/portage/cli/index/schema.rb

@@ -0,0 +1,70 @@
+require "sqlite3"
+
+module Portage
+  module Cli
+    module Index
+      # The SQL behind Index::Database, forward-only: MIGRATIONS[n] takes
+      # user_version n to n + 1.
+      module Schema
+        # Kept minimal: `data` is the entry's JSON verbatim. `products`
+        # carries an integer id (rather than the key alone being the
+        # primary key) only so products_fts can share its rowid, which
+        # stays stable across VACUUM.
+        SCHEMA = <<~SQL.freeze
+          CREATE TABLE stores (origin TEXT PRIMARY KEY, data TEXT NOT NULL);
+          CREATE TABLE products (id INTEGER PRIMARY KEY, key TEXT NOT NULL UNIQUE, data TEXT NOT NULL);
+          CREATE TABLE product_stores (key TEXT NOT NULL, origin TEXT NOT NULL, last_seen INTEGER,
+                                       PRIMARY KEY (key, origin));
+          CREATE TRIGGER products_stores_ins AFTER INSERT ON products BEGIN
+            INSERT OR REPLACE INTO product_stores (key, origin, last_seen)
+              SELECT new.key, json_extract(value, '$.origin'), json_extract(value, '$.last_seen')
+              FROM json_each(new.data, '$.stores');
+          END;
+          CREATE TRIGGER products_stores_upd AFTER UPDATE OF data ON products BEGIN
+            DELETE FROM product_stores WHERE key = old.key;
+            INSERT OR REPLACE INTO product_stores (key, origin, last_seen)
+              SELECT new.key, json_extract(value, '$.origin'), json_extract(value, '$.last_seen')
+              FROM json_each(new.data, '$.stores');
+          END;
+        SQL
+
+        # Needs FTS5 compiled in, which the gem's bundled SQLite has and a
+        # system-libraries build might not — see fts5_available?.
+        FTS_SCHEMA = <<~SQL.freeze
+          CREATE VIRTUAL TABLE products_fts USING fts5(key UNINDEXED, title, brand, category, aliases);
+          CREATE TRIGGER products_fts_ins AFTER INSERT ON products BEGIN
+            INSERT INTO products_fts (rowid, key, title, brand, category, aliases)
+              VALUES (new.id, new.key, json_extract(new.data, '$.title'), json_extract(new.data, '$.brand'),
+                      json_extract(new.data, '$.category'),
+                      (SELECT group_concat(value, ' ') FROM json_each(new.data, '$.aliases')));
+          END;
+          CREATE TRIGGER products_fts_upd AFTER UPDATE OF data ON products BEGIN
+            DELETE FROM products_fts WHERE rowid = old.id;
+            INSERT INTO products_fts (rowid, key, title, brand, category, aliases)
+              VALUES (new.id, new.key, json_extract(new.data, '$.title'), json_extract(new.data, '$.brand'),
+                      json_extract(new.data, '$.category'),
+                      (SELECT group_concat(value, ' ') FROM json_each(new.data, '$.aliases')));
+          END;
+          CREATE TRIGGER products_fts_del AFTER DELETE ON products BEGIN
+            DELETE FROM products_fts WHERE rowid = old.id;
+          END;
+        SQL
+
+        # Each entry is a script run at that user_version. The FTS one is a
+        # no-op on a build without FTS5 (its version still advances).
+        MIGRATIONS = [
+          ->(db) { db.execute_batch(SCHEMA) },
+          ->(db) { db.execute_batch(FTS_SCHEMA) if Schema.fts5_available? }
+        ].freeze
+
+        # @return [Boolean] whether the linked SQLite was built with FTS5.
+        def self.fts5_available?
+          db = SQLite3::Database.new(":memory:")
+          db.execute("PRAGMA compile_options").flatten.include?("ENABLE_FTS5")
+        ensure
+          db&.close
+        end
+      end
+    end
+  end
+end