story-teller 1.1.3

data/lib/story_teller/options.rb

@@ -0,0 +1,151 @@
+# lib/story_teller/options.rb
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+#
+# This file is part of the StoryTeller.
+#
+# The StoryTeller is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# The StoryTeller is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with the StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'logger'
+require 'optparse'
+
+require_relative 'version'
+
+# The StoryTeller module
+module StoryTeller
+  class UserError < StandardError; end
+
+  # The Options module
+  module Options
+    # The ArgumentsParser
+    class ArgumentsParser
+      attr_reader :parser, :options
+
+      def initialize(args, defaults = {}, option_parser = OptionParser.new, **params)
+        @args = args
+        @parser = option_parser
+        @options = defaults
+        flags.each { |method_name| self.method(method_name).call }
+        @parser.parse!(args, **params)
+      end
+
+      def flags
+        @flags ||= %i[
+          banner game_path admin builder persist word_wrap log_level
+          help version]
+      end
+
+      # rubocop: disable Metrics/MethodLength
+      def banner
+        @parser.banner = "Usage: #{File.basename($PROGRAM_NAME)} [game_path] [options]"
+        @parser.separator ''
+        @parser.separator 'Arguments:'
+        @parser.separator '    game_path                        Path to game file or directory'
+        @parser.separator(
+          format(
+            '                                     Default: %<game_path>s',
+            game_path: @options[:game_path]
+          )
+        )
+        @parser.separator ''
+        @parser.separator 'Options:'
+      end
+      # rubocop: enable Metrics/MethodLength
+
+      def game_path
+        first = @args.first
+        return if first.nil?
+
+        path = File.expand_path(first)
+
+        # Only treat it as game_path if it exists
+        return unless File.exist?(path)
+
+        @options[:game_path] = path
+        @args.shift
+      end
+
+      def admin
+        @parser.on_tail('--admin', 'Set player character as admin; default: false') do
+          @options[:admin] = true
+        end
+      end
+
+      def builder
+        @parser.on_tail('--builder', 'Set player character as builder; default: false') do
+          @options[:builder] = true
+        end
+      end
+
+      def persist
+        desc = 'Persist the world tree across sessions; default: false'
+        @parser.on_tail('--persist', desc) do
+          @options[:persist] = true
+          @options[:reset_db_each_session] = false
+        end
+      end
+
+      def word_wrap
+        @parser.on('--word-wrap COLUMNS', Integer, 'Set default line width') do |columns|
+          @options[:word_wrap] = columns
+        end
+      end
+
+      def log_level
+        @parser.on_tail('-v', '--verbose', 'Increase verbosity') do
+          @options[:log_level] ||= Logger::INFO
+          @options[:log_level] -= 1
+        end
+      end
+
+      def help
+        @parser.on_tail('-?', '--help', 'Show this message') do
+          puts @parser
+          exit
+        end
+      end
+
+      def version
+        @parser.on_tail('--version', 'Show version') do
+          puts "#{$PROGRAM_NAME} version #{StoryTellerCli::VERSION}"
+          exit
+        end
+      end
+    end
+    # class ArgumentsParser
+
+    def demand(options, arg, positional = false)
+      return options[arg] unless options[arg].nil?
+      required_arg = positional ? "<#{arg}>" : "--#{arg.to_s.gsub(/_/, '-')}"
+      raise UserError, "Required argument: #{required_arg}"
+    end
+
+    def parse_arguments(args: ARGV, defaults: {}, _file_path: ARGF)
+      arguments_parser = ArgumentsParser.new(args, defaults)
+      demand(arguments_parser.options, :game_path)
+      arguments_parser.options
+    rescue OptionParser::InvalidArgument, OptionParser::InvalidOption,
+           OptionParser::MissingArgument, OptionParser::NeedlessArgument => e
+      puts e.message
+      puts arguments_parser.parser
+      exit
+    rescue OptionParser::AmbiguousOption => e
+      abort e.message
+    end
+  end
+  # module Options
+end
+# module StoryTeller

data/lib/story_teller/persistence.rb

@@ -0,0 +1,340 @@
+# lib/story_teller/persistence.rb
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+#
+# This file is part of the StoryTeller.
+#
+# The StoryTeller is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# The StoryTeller is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with the StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'etc'
+require 'logger'
+require 'uri'
+require 'yaml'
+
+require 'sequel'
+
+require_relative 'database'
+require_relative 'snapshots'
+
+Sequel.extension :migration
+Sequel.extension :connection_validator
+
+# Simplistic in-memory cache
+class EphemeralCache < Hash
+  def get(key)
+    self[key]
+  end
+  def set(key, value, _ttl)
+    self[key] = value
+  end
+end
+
+# The Persistence class
+class Persistence
+  unless defined?(Persistence::GlobalCache)
+    GlobalCache = defined?(Java) ? java.util.concurrent.ConcurrentHashMap.new : EphemeralCache.new
+  end
+  Plugins = {
+    after_initialize: [],
+    caching: [Persistence::GlobalCache],
+    json_serializer: [],
+    xml_serializer: []
+  #   tactical_eager_loading: [],
+  #   eager_each: []
+  }.freeze
+end
+
+# The SequelLoggers module
+module SequelLoggers
+  DatabaseLogging = Struct.new(:memo).new({})
+
+  def add_logger(database, logger)
+    database.loggers << logger unless database.loggers.include?(logger)
+  end
+
+  def delete_logger(database, logger)
+    database.loggers.delete(logger) if database.loggers.include?(logger)
+  end
+
+  def set_log_level(database, level)
+    DatabaseLogging.memo[:preserved_log_levels][database] = database.sql_log_level
+    database.sql_log_level = level unless level.nil?
+  end
+
+  def enable_query_logging
+    DatabaseLogging.memo[:logger] ||= Logger.new($stdout)
+    DatabaseLogging.memo[:preserved_log_levels] ||= {}
+    logger = DatabaseLogging.memo[:logger]
+    Sequel::DATABASES.each do |database|
+      add_logger(database, logger)
+      set_log_level(database, :debug)
+      logger.debug "Enabled query logging for #{database}"
+    end
+  end
+
+  def disable_query_logging
+    logger = DatabaseLogging.memo[:logger]
+    Sequel::DATABASES.each do |database|
+      logger.debug "Disabling query logging for #{database}"
+      delete_logger(database, logger)
+      set_log_level(database, DatabaseLogging.memo[:preserved_log_levels][database])
+    end
+  end
+end
+# module SequelLoggers
+
+# The SequelPlugins module
+module SequelPlugins
+  def enable_plugins
+    Persistence::Plugins.each { |plugin, parameters| enable_plugin(plugin, parameters) }
+  end
+
+  def enable_plugin(plugin, parameters = [])
+    return Sequel::Model.plugin(plugin) if parameters.empty?
+    Sequel::Model.plugin(plugin, *parameters)
+  rescue LoadError => e
+    log.error e.message
+  end
+end
+# module SequelPlugins
+
+# module DatabaseResetHelpers
+module DatabaseResetHelpers
+  def reset!
+    db = Sequel::Model.db
+    tables = world_tables(db)
+    return if tables.empty?
+
+    db.from(*tables).truncate(cascade: true, restart: true)
+  end
+
+  def world_tree?
+    db = Sequel::Model.db
+    return false unless db.table_exists?(:object)
+
+    Inform::Object.dataset.any?
+  rescue Sequel::Error
+    false
+  end
+
+  def world_tables(db)
+    model_classes = Sequel::Model.descendants
+    tables = model_classes.filter { |model| concrete_world_model?(db, model) }
+    tables.map(&:table_name).uniq
+  end
+
+  def concrete_world_model?(db, model)
+    table_name = model.table_name
+    table_name && db.table_exists?(table_name)
+  rescue Sequel::Error
+    false
+  end
+
+  def without_committing!(&block)
+    Sequel::Model.db.transaction(rollback: :always, auto_savepoint: true, &block)
+  end
+
+  def world_object_ids
+    return Set.new unless Sequel::Model.db.table_exists?(:object)
+
+    Inform::Object.select_map(:id).to_set
+  rescue Sequel::Error
+    Set.new
+  end
+end
+
+# The StoryTeller module
+module StoryTeller
+  # The Persistence class
+  class Persistence
+    include DatabaseConnectionHelpers
+    include DatabaseResetHelpers
+    include SequelLoggers
+    include SequelPlugins
+
+    attr_reader :config, :environment
+
+    DEFAULT_DATABASE_NAME = 'default'.freeze
+
+    def self.init(env = nil, database_name = DEFAULT_DATABASE_NAME)
+      instance(env, database_name)
+    end
+
+    @instance_mutex = Mutex.new
+
+    def self.instance(*args)
+      return @instance unless @instance.nil?
+      @instance_mutex.synchronize do
+        @instance ||= new(*args)
+      end
+      @instance
+    end
+
+    private_class_method :new
+
+    def initialize(env = nil, database_name = DEFAULT_DATABASE_NAME)
+      @environment = env
+      @database_name = database_name
+      log.debug "Initializing persistence layer for environment: #{@environment}"
+      caller[0..4].each { |t| log.trace t }
+      @config = database_config.fetch(@environment.to_s, {})
+      establish_database_connection
+      enable_plugins
+      enable_query_logging if ENV['ENABLE_SQL_LOGGING']
+    end
+
+    def establish_database_connection
+      connect
+    rescue Sequel::DatabaseConnectionError
+      log.warn "Database requires initialization"
+      init_database(@database_name)
+      retry if DatabaseConnectionHelpers.connection_attempts < 2
+    end
+
+    def database_config
+      @database_config ||= YAML.load_file(database_config_file_path)
+    end
+
+    def database_config_file_path
+      @database_config_file_path ||= File.expand_path(
+        File.join(StoryTeller::Runtime.project_dir_path, 'config', 'database.yml')
+      )
+    end
+
+    def init_database(database_name)
+      @config = database_config.fetch('default')
+      connect
+      @database = Greenfield::Database.init(database_name)
+      @database.bootstrap.up
+      @config = database_config.fetch(environment.to_s)
+      connect
+    end
+  end
+  # class Persistence
+end
+# module StoryTeller
+
+# The StoryTeller module
+module StoryTeller
+  # The ImplicitMigration module
+  module ImplicitMigration
+    NoDatabasePattern = %r{No database associated with Sequel::Model}.freeze
+    MigrationSetupTemplate = '%<model>sSetup'.freeze
+    ModuleNamespaceDelimiterPattern = /::/.freeze
+
+    def before_inherited(subclass)
+      return if self != Sequel::Model
+      descendants << subclass
+      log.debug "#{subclass} << #{self} [#{descendants}]"
+      maybe_migrate(subclass)
+    end
+
+    def after_inherited(_subclass)
+      examine_schema
+    end
+
+    # rubocop: disable Metrics/AbcSize
+    # rubocop: disable Metrics/MethodLength
+    def examine_schema
+      descendants.each do |model_class|
+        table_name = model_class.table_name
+        indexes = self.db.indexes(table_name)
+        columns = model_class.columns
+        associations = model_class.associations
+
+        log.debug "Table: #{table_name}"
+        log.debug "Columns: #{columns.join(', ')}"
+        log.debug "Indexes: #{indexes}"
+
+        associations.each do |assoc_name, assoc_data|
+          log.debug "Association: #{assoc_name} (#{assoc_data[:type]}) to #{assoc_data[:class_name]}"
+        end
+
+        log.debug "==========="
+      end
+    end
+    # rubocop: enable Metrics/AbcSize
+    # rubocop: enable Metrics/MethodLength
+
+    def maybe_migrate(subclass)
+      migration_class = migration(subclass)
+      log.debug "Found migration class: #{migration_class}"
+      migration_class&.up
+    rescue Sequel::Error => e
+      if NoDatabasePattern.match?(e.message)
+        StoryTeller::Persistence.instance.connect
+        retry
+      end
+    end
+
+    def migration(model)
+      names = format(MigrationSetupTemplate, model: model).split(ModuleNamespaceDelimiterPattern)
+      names.inject(Object) do |mod, class_name|
+        mod.const_get(class_name)
+      rescue StandardError => e
+        log.warn "Error getting reference to migration model class: #{e.message}"
+        next
+      end
+    end
+  end
+  # module ImplicitMigration
+end
+# module StoryTeller
+
+# The StoryTeller module
+module StoryTeller
+  # The InheritanceListener module
+  module InheritanceListener
+    # The ClassMethods module
+    module ClassMethods
+      include StoryTeller::ImplicitMigration
+
+      def inherited(subclass)
+        before_inherited(subclass)
+        super
+        after_inherited(subclass)
+      end
+
+      # Returns the list of Model descendants.
+      def descendants
+        @descendants ||= []
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+  end
+  # module InheritanceListener
+end
+# module StoryTeller
+
+# The Sequel module
+module Sequel
+  # The Sequel::Model class
+  class Model
+    include StoryTeller::InheritanceListener
+
+    def self.implicit_table_name
+      underscore(demodulize(name)).to_sym
+    end
+  end
+end
+
+StoryTeller::Persistence.init(
+  StoryTeller::Runtime.instance.game.environment,
+  StoryTeller::Runtime.instance.game.name
+)

data/lib/story_teller/player_character.rb

@@ -0,0 +1,99 @@
+# lib/story_teller/player_character.rb
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+#
+# This file is part of the StoryTeller.
+#
+# The StoryTeller is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# The StoryTeller is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with the StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
+
+# module StoryTeller
+module StoryTeller
+  def self.PlayerCharacter(name)
+    Object(name, Character)
+  end
+
+  # class Character
+  class Character < Inform::Object
+    def initialize(name)
+      super
+      capacity 100
+      parse_name 0
+      orders 0
+      has :concealed, :animate, :proper, :transparent
+    end
+    def short_name; return L__M(:Miscellany, 18); end
+    def description; return L__M(:Miscellany, 19); end
+    def before; nil; end
+    def after; nil; end
+    def life; nil; end
+    def each_turn; nil; end
+    def time_out; nil; end
+    def describe; nil; end
+    def add_to_scope; nil; end
+    def number; 0; end
+    def before_implicit; nil; end
+  end
+end
+
+# module StoryTeller
+module StoryTeller
+  # module PersistedStartupLocation
+  module PersistedStartupLocation
+    Key = :story_teller_persisted_startup_location
+
+    module_function
+
+    def with(location)
+      previous = Thread.current[Key]
+      Thread.current[Key] = location
+      yield
+    ensure
+      Thread.current[Key] = previous
+    end
+
+    def peek
+      Thread.current[Key]
+    end
+
+    def clear
+      Thread.current[Key] = nil
+    end
+  end
+end
+
+# module StoryTeller
+module StoryTeller
+  # module PersistedStartupMove
+  module PersistedStartupMove
+    def move(object, destination)
+      persisted_destination = StoryTeller::PersistedStartupLocation.peek
+
+      if persisted_destination && startup_player_move?(object)
+        destination = persisted_destination
+        @location = persisted_destination
+        StoryTeller::PersistedStartupLocation.clear
+      end
+
+      super
+    end
+
+    private
+
+    def startup_player_move?(object)
+      object == @player || object == selfobj || object == StoryTeller::Engine.player_object
+    end
+  end
+end

data/lib/story_teller/privileges.rb

@@ -0,0 +1,55 @@
+# lib/story_teller/privileges.rb
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+#
+# This file is part of the StoryTeller.
+#
+# The StoryTeller is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# The StoryTeller is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with the StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
+
+# module StoryTeller
+module StoryTeller
+  # class InvocationIdentity
+  class InvocationIdentity
+    include StoryTeller::PrivilegedIdentity
+
+    attr_reader :runtime
+
+    def initialize(runtime)
+      @runtime = runtime
+    end
+
+    def identity
+      "runtime:#{runtime.identity}"
+    end
+
+    def privilege_label
+      'this runtime session'
+    end
+
+    def name
+      privilege_label
+    end
+
+    def privileged?(privilege)
+      runtime.privileged?(privilege)
+    end
+
+    def to_s
+      privilege_label
+    end
+  end
+end
+# module StoryTeller