gemba 0.1.1 → 0.2.0

data/lib/gemba/achievements/backend.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Gemba
+  module Achievements
+    # Abstract interface for achievement backends.
+    #
+    # All methods have no-op defaults so backends only need to override
+    # what they support. Concrete backends: NullBackend, FakeBackend,
+    # and the future RetroAchievements backend.
+    #
+    # Thread safety: do_frame is called from the emulation thread (Tk
+    # after-loop). on_unlock and on_auth_change callbacks fire on the
+    # same thread.
+    #
+    # Authentication lifecycle (decoupled from the real network):
+    #   1. call login(username:, token:) — may be async
+    #   2. on_auth_change callback fires with status :ok or :error
+    #   3. authenticated? reflects the current state
+    #   4. call logout to clear credentials
+    module Backend
+      # -- Authentication -------------------------------------------------------
+
+      # Initiate login with username + password (first-time auth).
+      # On success the on_auth_change callback fires with :ok and the
+      # returned API token is yielded so the caller can persist it:
+      #   on_auth_change { |status, token_or_error| ... }
+      # NullBackend ignores this call.
+      #
+      # @param username [String]
+      # @param password [String]
+      def login_with_password(username:, password:); end
+
+      # Resume a session using a previously stored API token.
+      # Called automatically at startup when credentials are already saved.
+      #
+      # @param username [String]
+      # @param token    [String]
+      def login_with_token(username:, token:); end
+
+      # Clear authentication state and stored session.
+      def logout; end
+
+      # @return [Boolean] true when authenticated and ready to serve achievements
+      def authenticated?
+        false
+      end
+
+      # Register a callback invoked when authentication state changes.
+      # Fired with `status` (:ok or :error) and an optional `error` message.
+      #
+      # @yield [Symbol, String, nil] status, error (nil on success)
+      def on_auth_change(&block)
+        @auth_callbacks ||= []
+        @auth_callbacks << block
+      end
+
+      # -- Game lifecycle -------------------------------------------------------
+
+      # Called once per emulated frame. Evaluate achievement conditions and
+      # fire on_unlock callbacks for any newly earned achievements.
+      #
+      # @param core [Gemba::Core] the live mGBA core
+      def do_frame(core); end
+
+      # Called when a new ROM is loaded. Backend should reset per-game state
+      # and re-identify the game.
+      #
+      # @param core     [Gemba::Core]
+      # @param rom_path [String, nil] path to the ROM file (used for MD5 hashing by network backends)
+      def load_game(core, rom_path = nil, md5 = nil); end
+
+      # Called when the ROM is unloaded / emulator stops.
+      def unload_game; end
+
+      # Called when a save state is loaded.  Memory jumped to an arbitrary saved
+      # state; all achievements must restart their priming/waiting sequence.
+      def reset_runtime; end
+
+      # -- Rich Presence --------------------------------------------------------
+
+      # Current Rich Presence display string for the active game, or nil if
+      # not loaded / not supported. Updated by do_frame in real backends.
+      def rich_presence_message
+        nil
+      end
+
+      # Enable or disable Rich Presence evaluation for the current game.
+      # Pushed from AppController when per-game config is resolved at ROM load.
+      def rich_presence_enabled=(val); end
+
+      # Register a callback fired when the Rich Presence string changes.
+      # Called with the new message string.
+      #
+      # @yield [String] the new rich presence message
+      def on_rich_presence_changed(&block)
+        @rp_callbacks ||= []
+        @rp_callbacks << block
+      end
+
+      # -- Achievement list -----------------------------------------------------
+
+      # Register a callback invoked when an achievement is unlocked.
+      # Multiple callbacks can be registered; all are called in order.
+      #
+      # @yield [Achievement] the newly earned achievement
+      def on_unlock(&block)
+        @unlock_callbacks ||= []
+        @unlock_callbacks << block
+      end
+
+      # @return [Array<Achievement>] all achievements for the current game
+      def achievement_list
+        []
+      end
+
+      # @return [Integer] number of earned achievements
+      def earned_count
+        achievement_list.count(&:earned?)
+      end
+
+      # @return [Integer] total achievements for the current game
+      def total_count
+        achievement_list.size
+      end
+
+      # Verify the stored token is still valid. Result fires on_auth_change.
+      # Used by the "Verify Token" button in settings.
+      def token_test; end
+
+      # @return [Boolean] true if this backend is active / enabled
+      def enabled?
+        false
+      end
+
+      # Fetch already-earned achievements from the server and merge them into
+      # the local earned state so the UI reflects prior progress. No-op for
+      # backends that have no server. Fires on_achievements_changed on
+      # completion.
+      def sync_unlocks; end
+
+      # Fetch the full achievement list for a given ROM (by RomInfo) purely for
+      # display — does not affect live game state. Calls the block with
+      # Array<Achievement> on success, or nil on failure/unsupported.
+      # No-op (calls block with nil) for backends without a server.
+      #
+      # @param rom_info [RomInfo]
+      # @yield [Array<Achievement>, nil]
+      def fetch_for_display(rom_info:, &callback)
+        callback&.call(nil)
+      end
+
+      # Set whether unofficial (Flags=5) achievements are included in
+      # display syncs and live evaluation. No-op for backends that don't
+      # distinguish official vs unofficial.
+      def include_unofficial=(val); end
+
+      # Register a callback invoked when the achievement list changes in bulk
+      # (e.g. after a game loads or sync_unlocks completes). Use this to
+      # refresh list UI without wiring individual on_unlock callbacks.
+      #
+      # @yield called with no arguments
+      def on_achievements_changed(&block)
+        @achievements_changed_callbacks ||= []
+        @achievements_changed_callbacks << block
+      end
+
+      private
+
+      def fire_unlock(achievement)
+        @unlock_callbacks&.each { |cb| cb.call(achievement) }
+      end
+
+      def fire_auth_change(status, error = nil)
+        @auth_callbacks&.each { |cb| cb.call(status, error) }
+      end
+
+      def fire_achievements_changed
+        @achievements_changed_callbacks&.each(&:call)
+      end
+
+      def fire_rich_presence_changed(message)
+        @rp_callbacks&.each { |cb| cb.call(message) }
+      end
+    end
+  end
+end

data/lib/gemba/achievements/cache.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'time'
+
+module Gemba
+  module Achievements
+    # Persistent per-ROM achievement cache.
+    #
+    # Stores the full achievement list (definitions + earned status) for each
+    # ROM as a JSON file under Config.achievements_cache_dir/<rom_id>.json.
+    # Written after every successful sync; read on demand by the window when
+    # a game is selected that isn't currently loaded in the emulator.
+    #
+    # Format:
+    #   { "synced_at": "<iso8601>",
+    #     "achievements": [ { "id":, "title":, "description":, "points":,
+    #                         "earned_at": "<iso8601>|null" }, … ] }
+    module Cache
+      def self.write(rom_id, achievements)
+        path = cache_path(rom_id)
+        FileUtils.mkdir_p(File.dirname(path))
+        data = {
+          'synced_at'    => Time.now.utc.iso8601,
+          'achievements' => achievements.map { |a|
+            {
+              'id'          => a.id,
+              'title'       => a.title,
+              'description' => a.description,
+              'points'      => a.points,
+              'earned_at'   => a.earned_at&.utc&.iso8601,
+            }
+          },
+        }
+        File.write(path, JSON.generate(data))
+        Gemba.log(:info) { "Achievements cache written: #{rom_id} (#{achievements.size} achievements)" }
+      rescue => e
+        Gemba.log(:warn) { "Achievements cache write failed for #{rom_id}: #{e.message}" }
+      end
+
+      # @return [Array<Achievement>, nil] cached list, or nil if no cache exists
+      def self.read(rom_id)
+        path = cache_path(rom_id)
+        return nil unless File.exist?(path)
+
+        data = JSON.parse(File.read(path))
+        list = (data['achievements'] || []).map do |a|
+          Achievement.new(
+            id:          a['id'].to_s,
+            title:       a['title'].to_s,
+            description: a['description'].to_s,
+            points:      a['points'].to_i,
+            earned_at:   a['earned_at'] ? Time.iso8601(a['earned_at']) : nil,
+          )
+        end
+        Gemba.log(:info) { "Achievements cache read: #{rom_id} (#{list.size} achievements, synced #{data['synced_at']})" }
+        list
+      rescue => e
+        Gemba.log(:warn) { "Achievements cache read failed for #{rom_id}: #{e.message}" }
+        nil
+      end
+
+      def self.cache_path(rom_id)
+        File.join(Config.achievements_cache_dir, "#{rom_id}.json")
+      end
+      private_class_method :cache_path
+    end
+  end
+end

data/lib/gemba/achievements/credentials_presenter.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Gemba
+  module Achievements
+    # Presents credential state for the RetroAchievements settings UI.
+    # Read-only view of state — never writes to disk or config.
+    #
+    # Initialized from persisted config. Mutated by:
+    #   - UI interactions (checkbox, keystrokes) via setters
+    #   - Backend auth results via :ra_auth_result bus events
+    #
+    # Emits :credentials_changed on the bus whenever state changes.
+    # SystemTab listens and calls apply_presenter_state to refresh widgets.
+    #
+    # Call dispose when discarding the presenter to remove the bus subscription.
+    class CredentialsPresenter
+      include BusEmitter
+
+      def initialize(config)
+        @enabled  = config.ra_enabled?
+        @username = config.ra_username.to_s
+        @token    = config.ra_token.to_s
+        @password = ''
+        @feedback_override = nil
+
+        @auth_handler = ->(status:, token: nil, message: nil) {
+          handle_auth_result(status, token, message)
+        }
+        Gemba.bus.on(:ra_auth_result, &@auth_handler)
+      end
+
+      # Remove bus subscription. Call before discarding the presenter.
+      def dispose
+        Gemba.bus.off(:ra_auth_result, @auth_handler)
+      end
+
+      # -- UI mutations ---------------------------------------------------------
+
+      def enabled=(val)
+        @enabled = val ? true : false
+        emit(:credentials_changed)
+      end
+
+      def username=(val)
+        @username = val.to_s
+        emit(:credentials_changed)
+      end
+
+      def password=(val)
+        @password = val.to_s
+        emit(:credentials_changed)
+      end
+
+      # Transient feedback (e.g. "Connection OK ✓") that disappears after a delay.
+      # Caller is responsible for scheduling clear_transient via Tk after.
+      def show_transient(key, **kwargs)
+        @feedback_override = { key: key, **kwargs }
+        emit(:credentials_changed)
+      end
+
+      def clear_transient
+        @feedback_override = nil
+        emit(:credentials_changed)
+      end
+
+      # -- Read-only accessors --------------------------------------------------
+
+      attr_reader :username, :password, :token
+      def enabled?   = @enabled
+      def logged_in? = !@token.strip.empty?
+
+      # -- Widget state queries -------------------------------------------------
+
+      def fields_state
+        return :disabled unless @enabled
+        return :readonly if logged_in?
+        :normal
+      end
+
+      def login_button_state
+        return :disabled unless @enabled
+        return :disabled if logged_in?
+        fields_filled? ? :normal : :disabled
+      end
+
+      def verify_button_state
+        (@enabled && logged_in?) ? :normal : :disabled
+      end
+
+      def logout_button_state
+        (@enabled && logged_in?) ? :normal : :disabled
+      end
+
+      def reset_button_state
+        (@enabled && logged_in?) ? :normal : :disabled
+      end
+
+      # Feedback descriptor. key drives locale lookup in SystemTab.
+      # :empty          → blank label
+      # :not_logged_in  → "Not logged in"
+      # :logged_in_as   → "Logged in as {username}"  (also carries username:)
+      # :test_ok        → "Connection OK ✓"
+      # :error          → error text (carries message:)
+      def feedback
+        return @feedback_override if @feedback_override
+        return { key: :empty }          unless @enabled
+        return { key: :logged_in_as, username: @username } if logged_in?
+        { key: :not_logged_in }
+      end
+
+      private
+
+      def handle_auth_result(status, token, message)
+        case status
+        when :ok
+          if token
+            # Login success — store token, clear password
+            @token    = token.to_s
+            @password = ''
+            @feedback_override = nil
+          else
+            # Ping success — show transient then let SystemTab schedule clear
+            @feedback_override = { key: :test_ok }
+            emit(:ra_token_test_ok)
+          end
+        when :error
+          @feedback_override = { key: :error, message: message.to_s }
+        when :logout
+          @token    = ''
+          @password = ''
+          @feedback_override = nil
+          # username intentionally kept so user can re-enter password quickly
+        end
+        emit(:credentials_changed)
+      end
+
+      def fields_filled?
+        !@username.strip.empty? && !@password.strip.empty?
+      end
+    end
+  end
+end

data/lib/gemba/achievements/fake_backend.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Gemba
+  module Achievements
+    # Pure-Ruby achievement backend for development and testing.
+    #
+    # Achievements are defined programmatically with a condition block
+    # that receives a memory-read helper. No HTTP, no hashing, no server.
+    #
+    # Authentication behaviour:
+    #   - By default any non-empty credentials succeed immediately.
+    #   - Pass `valid_username:` and `valid_token:` to restrict: only that
+    #     exact pair succeeds; anything else fails. Useful in tests that
+    #     verify the "bad credentials" error path.
+    #
+    # Used in two ways:
+    #   1. Automated tests — add achievements, step frames, assert unlocks
+    #   2. Integration dev — iterate on UI (toasts, list) without rcheevos
+    #
+    # @example Basic usage
+    #   backend = FakeBackend.new
+    #   backend.add_achievement(id: 'btn_b', title: 'Press B',
+    #                           description: 'Press the B button',
+    #                           points: 5) do |mem|
+    #     mem.call(0x02000000) == 0x42
+    #   end
+    #   backend.on_unlock { |ach| puts "Unlocked: #{ach.title}" }
+    #   backend.do_frame(core)  # call each frame
+    #
+    # @example Restricted credentials (for testing failure path)
+    #   backend = FakeBackend.new(valid_username: 'alice', valid_token: 'secret')
+    #   backend.login(username: 'bob', token: 'wrong')   # → fires :error
+    #   backend.login(username: 'alice', token: 'secret') # → fires :ok
+    class FakeBackend
+      include Backend
+
+      # @param valid_username [String, nil] when set, only this username passes
+      # @param valid_token    [String, nil] when set, only this token passes
+      def initialize(valid_username: nil, valid_token: nil)
+        @definitions = {}     # id → { achievement:, condition: }
+        @earned = {}          # id → Achievement (earned copy)
+        @prev_state = {}      # id → bool (condition result last frame)
+        @valid_username = valid_username
+        @valid_token = valid_token
+        @authenticated = false
+        @rich_presence_message = nil
+        @rich_presence_block   = nil
+      end
+
+      # -- Authentication -------------------------------------------------------
+
+      # Resolves immediately. Succeeds if credentials are non-empty and match
+      # the configured valid pair (or any non-empty creds if none configured).
+      # On success fires on_auth_change(:ok, fake_token) where fake_token is
+      # a deterministic stand-in so callers can exercise the token-persist path.
+      def login_with_password(username:, password:)
+        ok = !username.to_s.empty? && !password.to_s.empty? &&
+             (@valid_username.nil? || username == @valid_username) &&
+             (@valid_token.nil?    || password  == @valid_token)
+
+        if ok
+          @authenticated = true
+          fire_auth_change(:ok, "fake_token_for_#{username}")
+        else
+          @authenticated = false
+          fire_auth_change(:error, 'Invalid credentials (fake backend)')
+        end
+      end
+
+      def login_with_token(username:, token:)
+        ok = !username.to_s.empty? && !token.to_s.empty? &&
+             (@valid_username.nil? || username == @valid_username) &&
+             (@valid_token.nil?    || token    == @valid_token)
+
+        if ok
+          @authenticated = true
+          fire_auth_change(:ok, token)
+        else
+          @authenticated = false
+          fire_auth_change(:error, 'Invalid credentials (fake backend)')
+        end
+      end
+
+      def logout
+        @authenticated = false
+        fire_auth_change(:logout)
+      end
+
+      def token_test
+        if @authenticated
+          fire_auth_change(:ok, nil)
+        else
+          fire_auth_change(:error, 'Not authenticated (fake backend)')
+        end
+      end
+
+      def authenticated?
+        @authenticated
+      end
+
+      # Define an achievement. The block receives a read_mem callable
+      # and must return truthy when the unlock condition is met.
+      #
+      # @param id [String] unique identifier
+      # @param title [String]
+      # @param description [String]
+      # @param points [Integer]
+      # @yield [read_mem] called each frame; read_mem is ->(address) { Integer }
+      # @yieldreturn [Boolean] true when condition is satisfied
+      def add_achievement(id:, title:, description:, points: 0, &condition)
+        raise ArgumentError, "condition block required" unless condition
+        ach = Achievement.new(id: id, title: title,
+                              description: description,
+                              points: points, earned_at: nil)
+        @definitions[id] = { achievement: ach, condition: condition }
+        @prev_state[id] = false
+      end
+
+      # Evaluate all unearned achievements against current memory state.
+      # Fires on_unlock callbacks for newly met conditions (rising edge).
+      # Also evaluates the rich presence block if one is set.
+      #
+      # @param core [Gemba::Core]
+      def do_frame(core)
+        read_mem = ->(addr) { core.bus_read8(addr) }
+        @definitions.each do |id, defn|
+          next if @earned.key?(id)
+
+          current = defn[:condition].call(read_mem) ? true : false
+          if current && !@prev_state[id]
+            earned = defn[:achievement].earn
+            @earned[id] = earned
+            fire_unlock(earned)
+          end
+          @prev_state[id] = current
+        end
+
+        @rich_presence_message = @rich_presence_block.call if @rich_presence_block
+      end
+
+      def load_game(_core, rom_path = nil, md5 = nil)
+        @rich_presence_message = nil
+        @rich_presence_block   = nil
+        reset_earned
+      end
+
+      def unload_game
+        reset_earned
+      end
+
+      # @return [Array<Achievement>] all achievements, earned ones updated
+      def achievement_list
+        @definitions.map do |id, defn|
+          @earned[id] || defn[:achievement]
+        end
+      end
+
+      def enabled?
+        true
+      end
+
+      # Clear earned state (for test reuse).
+      def reset_earned
+        @earned = {}
+        @prev_state = @prev_state.transform_values { false }
+      end
+
+      # Set a Rich Presence message for testing.
+      #
+      # Pass a static string to return a fixed message:
+      #   backend.set_rich_presence("Playing World 1-1")
+      #
+      # Pass a block for dynamic messages evaluated each do_frame:
+      #   backend.set_rich_presence { "Frame #{frame_count}" }
+      #
+      # Call with no arguments to clear.
+      def set_rich_presence(string = nil, &block)
+        @rich_presence_block   = block || (string ? -> { string } : nil)
+        @rich_presence_message = string unless block
+      end
+
+      def rich_presence_message
+        @rich_presence_message
+      end
+
+      # Configure what fetch_for_display returns. Pass an Array (returned for
+      # every rom_info) or a block that receives rom_info and returns an Array
+      # or nil. Without calling this, fetch_for_display always calls back with nil.
+      #
+      # @example Always return a fixed list
+      #   backend.stub_fetch_for_display([ach1, ach2])
+      #
+      # @example Vary by rom_info
+      #   backend.stub_fetch_for_display { |rom_info| rom_info.rom_id == 'X' ? [ach1] : [] }
+      def stub_fetch_for_display(list = nil, &block)
+        @fetch_display_stub = block || ->(_) { list }
+      end
+
+      def fetch_for_display(rom_info:, &callback)
+        result = @fetch_display_stub ? @fetch_display_stub.call(rom_info) : nil
+        callback&.call(result)
+      end
+    end
+  end
+end

data/lib/gemba/achievements/null_backend.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Gemba
+  module Achievements
+    # No-op backend used when RetroAchievements is disabled.
+    # All methods are inherited no-ops from Backend.
+    class NullBackend
+      include Backend
+    end
+  end
+end